Add more HTTP Status Codes for improved Error Handling

[maxl2287]

Add more HTTP Status Codes for improved Error Handling

[RandyLevensalor]

This looks like a good improvement to include these error codes and they align with commonalities.

https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#6-error-responses

[jlurien]

Some of these errors, which not directly related to the API semantics but with general processing of an API gateway, are not generally explicitly documented in OAS specs. It is not obvious how certain codes should be documented, e.g. for 405 we would need to include all not allowed methods per path and document explicitly that 405 is to be returned if that verb is used.

Decision to add explicitly certain transversal responses to every operation of every CAMARA API is something that should be make clear in Commonalities. A possibility is to include all schemas under https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml#L130, with all generic codes + the API specific ones. But if we don't consider crossed $ref support between WG specs and common artifacts, maintenance will be complex and length of API specs will be increased a lot.

[hdamker]

@jlurien good points ... also for me it is unclear if the generic responses which are indicating that the API isn't used as specified must or even should be included within API Spec, especially all possible results with every operation. The same for the server errors which can happen with every operation like 500 and 503. Currently we have some kind of middle way within the spec ... some are listed, some other are not.

For me it would be currently enough if the transversal ones are listed only in the Design Guidelines and in https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml#L130.

What we need is something like the Design Guideline has done already for header parameters:

• defining if an error response must be listed within the OAS if the operation is allowed to return it
  • an example could be 501 ... the response must only be listed if an API Provider can decide to not implement the method
  • all application specific responses would belong here
• define which error response will not be listed within the OAS as a potential response
  • e.g. 405 does not make sense for me as a response for a specified method. In addition I would expect that only the defined methods are supported, so implicit all methods which are not defined may return 405.

For now, this issue and the PR my proposal would be to reduce the added error responses to 429, and don't add 405, 406 and 415.

[maxl2287]

@jlurien and @hdamker I understand and agree on your feedback.
I will remove everything instead 429

[hdamker]

@maxl2287 I fully understand the addition of 429 to createSession and extendDuration as there could be business quota cases, but I would question if we need to add the transversal case of a rate limiting error to every operation, especially within qos-profiles, as there no resources will be created. As a result there would be no changes to qos-profiles.