Documentation issues

[eric-murray]

Problem description

• Typo in POST /match endpoint description

  Possible values are:k          - **true**: the attribute provided matches with the one in the Operator systems, which is equal to a `match_score` of 100.
  

  The inclusion of k means that the first bullet point does not render properly

• Example Two-Legged and Three-leg Access Token Example: needs to be renamed. Following the replacement of 403 INVALID_TOKEN_CONTEXT with 422 UNNECESSARY_IDENTIFIER, this example will now result in an error for 3-legged access tokens.

• Review inclusion error code 404 NOT_FOUND, as it is not clear what would have to be NOT_FOUND for this error to be returned. If there is a valid use for this error code, document it.

  Error code 404 IDENTIFIER_NOT_FOUND would be used if the phoneNumber was explicitly provided, valid, but was not a phone number known to the API provider. But it is not clear that any other input parameter would result in either a NOT_FOUND or IDENTIFIER_NOT_FOUND error.

• Consider including and documenting the 429 errors. From Commonalities Design Guide:

  Error statuses 400, 404, 409, 422, 429: These error statuses SHOULD be documented based on the API design and the functionality involved. Subprojects evaluate the relevance and necessity of including these statuses in API specifications.

• Requirement for match score to use Jaro-Winkler distance algorithm is a little bit hidden in the documentation. Consider making this requirement clearer, and maybe provide a reference.

Expected action
Update documentation

Additional context
None

[PedroDiez]

Some comments to be aligned.

From the technical point of view:

• For 404 case, we think only applies IDENTIFIER_NOT_FOUND. Indeed, we do not have NOT_FOUND case in TEF implementations. Please also check this. Think we can delete it
• For 429 case, we think only TOO_MANY_REQUESTS scenario applies.

Regarding WoW:

• This issue is addressed before updating release-plan.yaml to Commonalities r4.4. A suggestion is to first trigger second RC track (comment related) and after that address this issue so we can take advantage of Common reusable schemas that will be imported locally in the repository:
  • IdentifierNotFound404 - https://github.com/camaraproject/Commonalities/blob/r4.4/artifacts/common/CAMARA_common.yaml#L517
  • TooManyRequests429 - https://github.com/camaraproject/Commonalities/blob/r4.4/artifacts/common/CAMARA_common.yaml#L624

Anyway it is fine if preferred this way now and align after

@GillesInnov35, @ToshiWakayama-KDDI
cc @eric-murray