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 common.yaml unnecessarily list ErrorInfo properties as required. #162
• Output for Issue Which error send back when issue with Device Identifier provided by the API Consumer? #127
• Error Model Alignment Revision of Chapter 6 Error Responses in API Design Guidelines #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

[patrice-conil]

Nice work ... one typo to fix but LGTM

[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 (camaraproject/QualityOnDemand#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).

[rartych]

Do we need this error specified?
If so, then DD.BB. level is not clear for me.

[PedroDiez]

In the description i was referring that when this happens one of the reasons can be at DD.BB. level (problem in DD.BB. system providing support to API BE). It is fine to me to rephrase to:

Some data is lost or corrupted when the server is processing the request so as it cannot manage it properly

On the other hand, Currently it is not used in any API. So, we could take out so far
WDYT? @rartych, @patrice-conil

[PedroDiez]

removed DATA_LOSS error code

[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 )

[patrice-conil]

I support removing DATA_LOSS because I don't see any use cases using it

[shilpa-padgaonkar]

/LGTM

[patrice-conil]

LGTM