Should the headers like x-correlator be included in OAS definition?

[rartych]

Problem description
Proble occured in conversation to PR #88
Currently the table in API Design Guidelines "Required in OAS Definition" states "No" for both "X-Correlator" and "X-Version"
X-Correlator header is included in some CAMARA API definitions.

In section 3.5 in relation to security related headers guidelines are:

To avoid cluttering the CAMARA OAS (Swagger) definition files, the above headers must not be included explicitly in the API definition files even when supported, as it can be assumed that developers will already be familiar with their use.

Expected action
The column "Required in OAS Definition" should rather be "Included in OAS Definition" and binding for all CAMARA APIs.
Or the whole section 9. Architecture Headers can be integrated within section 3.5.

Additional context
The more common names for header used to correlate HTTP requests between a client and server are X-Correlation-ID or Correlation-ID
https://en.wikipedia.org/wiki/List_of_HTTP_header_fields

[RubenBG7]

Hi @rartych ,

From Telefonica , we are requesting an altenative method to inform to the consumers that the x-orrelator header are available to be used in the OAS3. That's what we are waiting for... we have not received any contingency, then we are still maintaining the definition till we agree an alternative.

I Know that the x-correlator is defined in the column "Required in OAS Definition" as NO, but not required does not mean "forbidden"

Hope you know what I meaning.

[MarkCornall]

Whatever the solution. We must ensure operability across operators. Developers should not need to change their headers for any API to work on different operators.

[eric-murray]

Given that X-Correlator is not standard and requires value checking, as it must be a UUID, I think the simplest approach for both API consumers and implementors is to explicitly include this header in the OAS definition. It will not add too much clutter.

Bur X-Version should be deleted or, at least, not mandatory to include or support, as nobody seems to know what this is for.

[RubenBG7]

Totally agree @eric-murray to include x-correlator in OAS and delete x-version from the guidelines.