MISSING_IDENTIFIER error message can mislead API client developer

[gregory1g]

Problem description
https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#61-standardized-use-of-camara-error-responses defines error message for MISSING_IDENTIFIER as
"An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token".

At the same time, if a request which uses 3-legged token includes device id in the request body, error UNNECESSARY_IDENTIFIER must be returned.

Therefore,

• if an API invoker uses a 3-legged token and the server cannot extract device id from the token, reference to the request body (""An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token"") is misleading - this developer is not allowed to send device id in the request.
• if an API invoker uses a 2-legged token and does not send device id in the request, reference to the 3-legged token ((""An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token"")) is also misleading - this 3-legged token was not used.

Expected behavior
Suggestion: change error message to more neutral version:
"An identifier is not included in the request and the device or phone number identification cannot be derived from the access token"
This text will match both scenarios.

[eric-murray]

Hi @gregory1g

I think it is the error description rather than the example error message that you believe to be potentially misleading. Error messages in CAMARA documentation are anyway always examples - implementations can always use their own error messages as appropriate.

If agreed to update the description, this will also need to be updated in CAMARA_common.yaml, as well as in the API design guidelines.

[gregory1g]

yes, you are right this is the description, not error message. Still, it would be good to remove confusion from the text.

I also suggest to explicitly add explanation that "Message Example" in error messages table is just an example and more appropriate text can be used in a specific API. The reason for this is: unfortunately, the "example" nature of the text is not that obvious as one could expect. I saw discussions where the error text improvement suggestion was rejected with the argument "the text is defined in commonalities exactly this way".

[eric-murray]

The Commonalities API Design Guidelines do contain a statement that message values are only examples and can be changed:

All these aforementioned fields are mandatory in Error Responses. status and code fields have normative nature, so as their use has to be standardized (see Section 6.1). On the other hand, message is informative and within this document an example is shown.

It is recognised that the design guidelines is a big document which does not readily distinguish between "guidance" and "requirements". It will be re-written at some point.