Guidelines for processing x-correlator in API definitions

[rartych]

Problem description
Currently API Design Guidelines include instructions how to treat x-correlator

When the API Consumer includes non-empty "x-correlator" header in the request, the API Provider must include it in the response with the same value that was used in the request. Otherwise, it is optional to include the "x-correlator" header in the response with any valid value. Recommendation is to use UUID for values.

In notification scenarios (i.e., POST request sent towards the listener indicated by sink address), the use of the "x-correlator" is supported for the same aim as well. When the API request includes the "x-correlator" header, it is recommended for the listener to include it in the response with the same value as was used in the request. Otherwise, it is optional to include the "x-correlator" header in the response with any valid value.

This instruction is not added to API definitions in YAML, so developers of API and API clients need to look into API Design Guidelines to learn how to process this header.

Possible evolution
Add an example of text to be included in inline API documentation in the YAML file.

Alternative solution
Create separate document: "API Implementation Guidelines" that explains how to implement specific features of CAMARA APIs, error codes not documented in YAML, usage of Trace Context, etc.

Additional context

[eric-murray]

A separate set of Implementation guidelines is fine, but they should be informative and not normative. Anything normative must be defined in the API design guidelines.

Generally, the assumptions we can make are:

• Developers of API provider implementations should absolutely know what they are doing
• Developers of API consumer (client) implementations should have a pretty good idea of what they are doing
• Users of client implementations can be forgiven for just looking at the YAML