-
Notifications
You must be signed in to change notification settings - Fork 22
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add x-correlator as header attribute #49
Comments
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:
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 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. |
@hdamker Agreed with you on the way to proceed:
|
Just commenting on 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 And anyway, it really is far better if the API consumer doesn't provide an |
@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. |
Hi @bigludo7 My preference was always that API definitions do NOT explicitly include the common CAMARA defined headers (currently In particular:
My preferences are:
|
Thanks @eric-murray for the clarification. I support your preference:
So probably next step is to propose a change in commonalities (I can do it but will wait to complete the notification part before) |
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? |
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 So my proposal for the design guidelines is that the request header is optional but the response header mandatory. |
There is some update on this topic here: camaraproject/Commonalities#88 |
PR created to include the x-correlator header as it seems commonalities is aligning to include it |
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
The text was updated successfully, but these errors were encountered: