Add x-correlator as header attribute

[bigludo7]

Problem description
As defined in the Commonalities - Design guideline, X-Correlator attribute in header must be added

Possible evolution
Add this attribute.

Alternative solution

Additional context

[hdamker]

@bigludo7

I would like to understand better where the CAMARA design guidelines require to add this header attribute into the OAS file. I don't question that the header attribute must be supported if the API caller sends it, I'm just questioning that it must be included in the OAS specification and clutter it (there are lot of well-known headers which need to be supported). I'm especially asking as your issue raised here is for me a precdent for other sub project.

In more detail: chapter "3.5 HTTP Header Definitions" list a lot of HTTP headers and says rightfully:

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.

Then there is chapter "9. Architecture Headers" which is unfornately not linked with 3.5. It has a table of "common headers" which "should be included". One ot the two is X-Correlator. But first it isn't a "must", the API Caller isn't required to send it, and - most relevant for the issue here - the table says exlicitly that it is not "required within the OAS file".

If you agree with my interpretation, we should close the issue here and open one in Commonalities to make the Guidelines less ambiguous, e.g. list "X-Correlator" also in chapter 3.5 as a common header and add some explanation withinn chapter 9 what the chapter means for API implementations.

[bigludo7]

@hdamker
I've raised this issue initially here following feedback from developer implementing our API who did not understand why Number Verification API feature the X-Correlator while not SimSwap API. As they implemented both API the inconsistency was highlighted. I was chasing a quick resolution on this but probably better to have also the global picture of all API

Agreed with you on the way to proceed:

• We close this issue
• We need to update the design guideline. I'm not sure about this chapter 9 value. As you write, we should move the information in this chapter 9 in a paragraph of 3.5.
• Probably for global consistency we should enforce presence of x-correlator in all our api.
• Then we can again raise issue in API without this header parameter.

[eric-murray]

Just commenting on X-Correlator (and X-Version) in the API Design Guidelines, the decision on whether or not these should be included in the OAS definition was a bit of a compromise. The agreement was that they can be optionally documented, but this is not required (see column "Required in OAS Definition" of the table in the Architecture Headers section of the API Design Guidelines). The question is "why do you think it should be documented in the OAS?".

My own view is that it should not be included, for various reasons that I can go into if this is re-opened in Commonalities. But not least of these is that the API Design Guidelines say X-Correlator is a UUID, but the Number Verification API definition and the PR for SIM Swap are defining it as simple a string, thus already introducing an inconsistency with the Design Guidelines. So I think it better that the Design Guidelines be the "source of truth", and the individual API documentation just link to these.

And anyway, it really is far better if the API consumer doesn't provide an X-Correlator value at all in their request.

[bigludo7]

@eric-murray About Design Guidelines as 'source of truth' completely aligned- if we stated it that it is an UUID we must have it as UUID in the API.

I do not have your knowledge on the topic but my point is that I'm not conformable with the idea that some CAMARA API will have this attribute while other will not. I had already this feedback form my dev team implementing this API. WDYT of this possible inconsistency between API ? It means that we have to ask the presence of the field api per api ... looking for your guidance.

[eric-murray]

Hi @bigludo7

My preference was always that API definitions do NOT explicitly include the common CAMARA defined headers (currently X-Correlator and X-Version), but rather their (possible) support would be known from the API design guidelines. And whilst no API did explicitly include them, then that was fine. But now I think we need to take this back to Commonalities for clarification.

In particular:

• Is support for these headers by the API implementation mandatory? This is not defined.
  • If not mandatory for all APIs:
    • Can a specific API make it mandatory and thus include these headers in the API definition?
    • Or should we leave it each implementation to decide if they support these headers, and indicate this in their own customised version of the API definition?
  • If mandatory, will a statement to this effect in the API Design Guidelines be sufficient for developers to know about them, or do developers not read API Design Guidelines?
• What is the X-Version header for and how should the API implementation use it? I have no idea.

My preferences are:

• Make support for X-Correlator mandatory for all API implementations (but still optional for API consumer to include in their request)
• Each API definition to include a link to the API Design Guidelines with a statement along the lines of "See here for supported architecture headers"
• X-Version should be removed from the design guidelines unless someone comes up with a convincing use case for this

[bigludo7]

Thanks @eric-murray for the clarification.

I support your preference:

Make support for X-Correlator mandatory for all API implementations (but still optional for API consumer to include in their request)
Each API definition to include a link to the API Design Guidelines with a statement along the lines of "See here for supported architecture headers"
X-Version should be removed from the design guidelines unless someone comes up with a convincing use case for this

So probably next step is to propose a change in commonalities (I can do it but will wait to complete the notification part before)

[fernandopradocabrillo]

• Make support for X-Correlator mandatory for all API implementations (but still optional for API consumer to include in their request)
• Each API definition to include a link to the API Design Guidelines with a statement along the lines of "See here for supported architecture headers"
• X-Version should be removed from the design guidelines unless someone comes up with a convincing use case for this

Hi @eric-murray, just to clarify, your point is to not include the header into the OAS file and clarify in the API guidelines that it should be supported by the implementator in case the consumer uses it?

[eric-murray]

Hi @fernandopradocabrillo

Yes, that's correct, though note that the usual way these correlation headers are implemented is that, if the API consumer does not provide a value, then one is automatically generated. So the response will include an X-Correlator even if the request did not. In fact, it is preferable for the API consumer not to provide a correlation header, because some have an annoying habit of using the same value repeatedly.

So my proposal for the design guidelines is that the request header is optional but the response header mandatory.

[bigludo7]

There is some update on this topic here: camaraproject/Commonalities#88

[fernandopradocabrillo]

PR created to include the x-correlator header as it seems commonalities is aligning to include it