How to indicate or handle when a multi-endpoint API is only partially implemented?

[MarkCornall]

Some of our APIs have more than one end point. eg Number verification has both a "verify" and "share" endpoint. Most companies implement both end points. However in some cases due to local regulation only one endpoint is implemented. It is possible that this is not a choice but guidance of local regulation.

Existing rules are to not amend the CAMARA .yaml file even when publishing locally. If you do amend then the API is no longer CAMARA standard.

However, A common way to handle such partial implementations is required. CAMARA APIs are already quite atomic and further separation may not be the best solution.

Please can commonalities review the issue and amend guidance and documentation as appropriate?

[bigludo7]

To link Mark request to previous discussion on this topic: we had a closed issue: #246 and an TSC discussion here.

[hdamker]

@MarkCornall as @bigludo7 has already mentioned: this is a topic which was discussed and is documented. There are multiple options to deal which such situation:

• split the API into more atomic ones if there are no dependencies between the endpoints and it is possible (e.g. as done in DeviceLocation)
• design the API in a way that allow all parties to implement it as intended with all endpoints within the local regulation boundaries (that has happened for SimSwap with the introduction of the "monitored period")
• or, as a last resort, allow API Providers to respond with 501 (NOT_IMPLEMENTED) for certain endpoints. That indicates to API Consumers the potential partial implementation. This option is intentionally discouraged to avoid fragmentation (cf. https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md#31-standardized-use-of-camara-error-responses)

All these options need to be discussed for the concrete case, therefore it is best to raise a concrete issue within the affected API repository to find the best solution there.