Update API-design-guidelines.md

[eric-murray]

What type of PR is this?

• documentation

What this PR does / why we need it:

The current API guidelines do not specify the conditions under which the API provider includes the X-Correlator header in their response to an API request. This PR clarifies that the API provider:

• must include the X-Correlator header in the response if it is included in the request
• otherwise it is optional for the API provider to include the X-Correlator header in their response

Which issue(s) this PR fixes:

N/A

Special notes for reviewers:

None

Changelog input

 release-note
 - Clarification of conditions under which the API provider includes the `X-Correlator` header in their response to an API request

Additional documentation

None

[patrice-conil]

/LGTM
Need to check existing API because I think some of them reference "x-correlator" in lowercase.

[eric-murray]

@patrice-conil
I did a small update to clarify that the same UUID should be in response as in request. So you will need to re-review.

On header naming, I'm happy for ALL headers to be written in lower case only, as it makes no difference to their use or purpose, but that is for a separate issue. The current definition of "X-Correlator" was proposed by Telefonica, and I don't want to make unilateral proposals to change that without understanding why they originally chose Pascal case.

[PedroDiez]

Just to comment here and aligned with @RubenBG7 that, understanding the proposal, this does not mean to remove the header "x-correlator" from yaml.

There is no contingency to inform consumers that they can use the header if not indicated in the YAML. Consumers do NOT have to know the CAMARA API Design guidelines. Point that was commeted by TEF in latest commonalities meeting (as per alignment done with Rubén)

[eric-murray]

@PedroDiez
Indeed, there is no change on that point. As originally defined by Telefonica, "Required in OAS Definition" remains "No" for both "X-Correlator" and "X-Version". I'm not proposing any changes to that field.

[PedroDiez]

@PedroDiez Indeed, there is no change on that point. As originally defined by Telefonica, "Required in OAS Definition" remains "No" for both "X-Correlator" and "X-Version". I'm not proposing any changes to that field.

Get your point Eric, what i want to highlight is the fact that it is not required in OAS definition does not enter in contradiction with its indication in YAML (for sure as optional field) and that also help API consumers

[hdamker]

Get your point Eric, what i want to highlight is the fact that it is not required in OAS definition does not enter in contradiction with its indication in YAML (for sure as optional field) and that also help API consumers

@PedroDiez @eric-murray that will not work for CAMARA - we need to be consistent across the APIs in CAMARA and should not keep this point open for decision in every sub project.

My understanding is that it is agreed that the support for X-correlator is mandatory for every API provider (which means if the APi consumer provides the header, it has to be in the response). That is valid for every CAMARA API.

But then we need to be consistent regarding including it into the YAML file of CAMARA APIs. It can't be that some APIs include it and others not. So the column "Required in OAS Definition" should rather be "Included in OAS Definition" and than binding for all CAMARA APIs.

The next question is than if the value should be "No" or "Yes".

I tend to "No" (not to clutter the YAML files). But we might need anyway general documentation

• for CAMARA API consumers which includes the headers which they can expect and their behaviour (beside other things like authentication and authorization flows). This could be linked within every YAML
• maybe also for CAMARA API provider/implementors (if not covered by the Design Guidelines already)

[hdamker]

One other point which is related to the chapter Architecture Header but may require a new issue (or is already addressed in another issue?):

What is this "X-Version" about ... it's expected from the API consumer ... what is the meaning, what can the API provider expect here, what should the API provider do with it? Currently this is completely undefined ... therefore I would rather delete it from the document (which would allow to rename the chapter to "Correlation ID" or similar.

[eric-murray]

@hdamker
I agree that the issue of whether X-Correlator must or must not be included in the YAML remains to be resolved, but that was not the point of this PR! I would suggest that a new issue is opened to discuss this.

Regarding X-Version, I asked the same question in the last Commonalties meeting, as was told it was a type of User-Agent header. I can't think of any CAMARA-specific uses for this header either.

[PedroDiez]

@hdamker Agree this is an orthogonal point to this pull request.
Mention here @RubenBG7, just to be informed about this topic in YAML.

No more discussion in this thread from my side

[RubenBG7]

As we comment in the last commonalities, it is still pending how we inform to the consumers that the x-correlator is available to be used in all CAMARA APIs.

"Consumers shall known the API design guidelines" IT IS NOT A SOLUTION. Because consumers shall not Know anything about design guidelines, there exist for designers and not for consumers.

When a contingency to that issue will be agreed, as @hdamker says we shall apply it to all APIs to be compliant with ourselfs

[patrice-conil]

@hdamker I agree that the issue of whether X-Correlator must or must not be included in the YAML remains to be resolved, but that was not the point of this PR! I would suggest that a new issue is opened to discuss this.

Regarding X-Version, I asked the same question in the last Commonalties meeting, as was told it was a type of User-Agent header. I can't think of any CAMARA-specific uses for this header either.

I agree with @eric-murray,
I understand the use of X-Correlator (I would have preferred a "more standard" header like X-Request-ID or X-Correlation-ID or one from OpenTelemetry like SpanId or TraceId, but I can live with X-Correlator).
However I don't see any use for the X-Version.

[rartych]

I propose to close the discussion here and merge the PR.
The open question should be resolved in the new issue #101