error_model_alignment

[PedroDiez]

What type of PR is this?

Add one of the following kinds:

• correction
• enhancement/feature
• documentation

What this PR does / why we need it:

This PR covers mainly 3 topics:

• Clarify error model properties are all mandatory. Issue #162
• Output for Issue #127
• Error Model Alignment #180

Documentation Impacted:

• API Design Guidelines (sections 3.2 and section 6, new sections 6.1 and 6.2)
• CAMARA_common.yaml (aligment of message examples and ordering responses model by status)

Which issue(s) this PR fixes:

Fixes #127 Fixes #128 Fixes #162 Fixes #172 Fixes #180

Special notes for reviewers:

Regarding API design guidelines, section 6.2 could also be documented in a separate file (.md for instance and refer from that section). I preferred to explicitly reflect to be easy to get the aim of the section.

@rartych regarding Issue #180 in case you were thinking in additional points I can just take out (Fixes #180) and only reference in the (#### What this PR does / why we need it:) as partial fixing

Changelog input

 - Clarify Error properties are required
 - Error model for device Identifier
 - Added clarification about AuthN/AuthZ standardized flows follow their own Error Response format
 - Error model alignment

Additional documentation

Not apply

[rartych]

To tackle #128 and #172 and similar questions I suggest to add paragraph like:

When standardized authentication flows are used - cf. 10.2 Security Implementation the format and content of Error Response should follow relevant standards.

It can be in error format definition or particularly for 401 Status.

[jlurien]

I have linked another related discussion in QoD (https://github.com/camaraproject/QualityOnDemand/pull/297) to define the status and code error for situations when a request is rejected due to exceeding a business quota limit. A new code QUOTA_EXCEEDED makes sense, but status could be either 429 or 403. The first being more related to rate limiting and the second a more generic "forbidden due to business logic".

I will align the PR in QoD with the decision here. cc @PedroDiez

[PedroDiez]

Actions covered in commit 4611515ce7eedb10c961d14b1ccb3966dcdc447b

• Suggestion by Patrice
• Suggestions by Rafal to unify info and add clarification for Issues#128 and Issue#172
• Added QUOTA_EXCEEDED code, based on topic raised by Jose. Proposed to be 429 status in the sense it is focused in a business quota limit that has been overpassed (e.g. number of N QoD minutes or sessions per period). Also fine to be 403 in case seen more suitable.

[PedroDiez]

Actions covered in commit 082f5e52ddec8920432fe12d97cbce62e4cb5fb3

• Grouping in responses section all the ones that own the same status due to an API that responds to a status must reference a single responses object (it cannot indicate that it is an anyOf and show N $refs).

[PedroDiez]

05/JUN: Addressed first round of reviews

Pending point:

• Exception 500 DATA_LOSS. Should we take out so far? (please see above comment @rartych, @patrice-conil )