Request Tracking ID for CAMARA API

[psidana1983]

Hi Team ,

The provided CAMARA APIs doesn't have any request field to

• capture a uniqueId that can be helpful for end to end tracking of the request
• requested system to understand who is consuming the service .

So i want to understand if we can modify the APis to have such generic fields in the request. It will be very helpful for troubleshooting.

[eric-murray]

Converting to discussion

[bigludo7]

Hello,
Up to me understanding

• for E2E tracking you can use the X-Correlator --> see https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/API-design-guidelines.md chapter 9
• For the consumer this need to be detailed as probably my first answer will be that this information is link to API client id provided during token retrieval.

Hope it helps

[psidana1983]

hi
So you mean i can have below header parameters in my request ? Are they mandatory parameters?
X-Version
X-Correlator

Also, why these parameters are missing in the resource documentation ? If i have to use them then should i update my documentation with these parameters and if I update my documentation then can I be CAMARA complaint ?

I think we shall have more header parameters
clientId
ClientName -> by looking at the clientId i cannot find the client Name so i believe we should have this field
RequestDateTime -> Time at which the request was initiated
Authorization -> To capture the bearer token for OAuth

Please share your view

[eric-murray]

The X-Version, X-Correlator and Authorization headers are already discussed in the CAMARA API Design Guidelines. Please read this document carefully before commenting further.

RequestDateTime is not a standard header. Did you just invent this? Maybe you are thinking of Date. The client can send the Date header if it wants, but there is no value in this header to the API gateway.

Which implementation of OAuth are you using that does not allow you to identify the client that was issued the token?

[psidana1983]

Hi Eric,

RequestDateTime is just a reference i used . It can be called as "date" aswell. What do you mean by "there is no value in this header to the API gateway" .

My OAuth does allow me to identify the client , no issues in that . May be i couldn't explain my point properly . Sorry about that .
Allow me to ask it again

I want to capture the client name so that I can log it and use it for troubleshooting , if required. So was checking if we can add this aswell in the header.

Meanwhile, please suggest on below aswell
Don't we need to capture these header parameters in the resource documentation ? If i have to use them then should i update my documentation with these parameters and if I update my documentation then can I be CAMARA complaint ?

[eric-murray]

There is nothing to stop a client sending a Date header, but it will almost certainly be ignored. Perhaps have a read of the IETF draft on this topic, and let us know which of the scenarios discussed you think applies here and why.

If you can identify the client from the OAuth token, then you have a name for the client. If your tooling is not passing that name on to you for logging, then you have an issue with your tooling. If you want to ask your clients to include a ClientName header, then they may oblige, but most implementations do not require this, so it will not be made mandatory.

The CAMARA API Design Guidelines are part of the CAMARA documentation, and explain the CAMARA position on documenting headers.

[psidana1983]

Thanks Eric .

[psidana1983]

Meanwhile , I saw that field - "X-Correlator " can be used both in request and response . I understand for request I shall add it under Header but how about response? If add it in the response schema then it will change the CAMARA defined response structure , isnt it ?

Current Response Structure :
{
swapped:false
}

Am I allowed to change it as
{
swapped:false
X-Correlator : bbc48-ffshr0-nnse2
}

Please suggest

[eric-murray]

X-Correlator is a header, not a body parameter. For requests, this header is optional. It should be included in the response whether or not it was included in the request, but this is not mandated.