API Design Guidelines and the Inclusion of Headers in the API Specification

[eric-murray]

The API Design Guidelines list many possible headers that can be included in an API request and/or response. Some recommendations and requirements about the use of headers is included, but no guidance about how headers should be captured within the Open API Specification itself.

The OAS specification itself only has one requirement on the inclusion of headers:

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored.

In other words, use of the "Accept", "Content-Type" and "Authorization" is so well understood, that there is no point in explicitly including them because all you will do is introduce the possibility of confusion.

Currently, CAMARA API specifications are taking different approaches to the specification of headers. I think a common approach should be agreed, and I think that should be a minimalist approach. Specifically:

• Only custom headers essential for the operation of the API be explicitly defined within the API specification
• Any headers mentioned in the API Design Guidelines should not explicitly be included in the API specification itself, not even essential standard headers (such as "Accept", "Content-Type" and "Authorization")
• A link to the current API Design Guidelines should be included within the API specification to guide those who want to know what request headers will be accepted and what response headers should be expected

If we can agree on this approach, then I'll propose an update to the API Design Guidelines which clarify how headers should be treated within the API specification itself.

[RubenBG7]

Hi Eric!,

Relative to de essential standard headers, totally agree following OAS3 definitions.

Relative to Only custom headers essential for the operation of the API be explicitly defined within the API specification, I'm not agree with that affirmation, because an API contract should be idempotent, I mean that when dev people take API contract to implement it, they shouldn't need check any other document to understand all the fields involved.

[eric-murray]

Hi Rubén

Probably we need some agreement on what an "essential" header is. I tested our implementation of the QoD API, and found that it failed if I did not include any of the following headers:

• Authorization
• Content-Type
• Content-Length
• Host

Maybe other implementations are different.

Now Authorization and Content-Type should not be included in the API specification according to OAS rules (or, rather, if included, they will be ignored). But I've not seen an API specification that includes Content-Length or Host explicitly either. Rather, it is implicitly assumed that developers know how to use these standard headers (and most tooling appears to generate them automatically anyway).

So my view is that any standard header included in the API Design Guidelines (essential or not) should not explicitly be included in the API specification because it is assumed that developers know how to use standard headers (having said that, the API Design Guidelines do not currently mention the Host header, so a PR is required for that).

But there may be exceptions. There may be APIs that require a header that might normally be considered optional, or use a header in an unexpected way. The rule could be that standard headers should not be explicitly listed unless they are being used in a "non-standard" way by the API.

[jlurien]

Hi, I think we should distinguish between

• standard HTTP headers, which many of them are essential but are not usually make explicit in each API definition, as OAS spec discourage, and
• proprietary or custom headers, that we may define on top of the standard ones, for example an x-correlator header.

Some of these proprietary headers may be transversal to all CAMARA APIs, but we should define them within each API spec, or at least have a $ref within each spec to a common place where common stuff is defined.

[eric-murray]

@jlurien
I think the only "CAMARA proprietary" headers currently defined within the API Design Guidelines that we might want to explicitly put into the API specification are X-Correlator and X-Version. Neither of these is essential to the operation of an API, so this would just be a reminder to the developer that they might be supported. BTW, X-Version is just a response header? It doesn't make sense to me as a request header.

My instinct is still to leave such "helper headers" in the design guidelines and put a link to those in the API specification itself. But these are only two headers, so not a great burden to add explicitly. If the number of proprietary but non-essential headers increased however, API specifications might start to get cluttered.

[patrice-conil]

I totally agree with Eric

[RubenBG7]

Added change on PR #161

[eric-murray]

Thanks @RubenBG7 for taking on this PR.

Can you expand it to include the following additional information?

• In the Architecture Headers section, can you add columns to indicate whether the header is a request header, response header or both. My understanding is:
  • X-Version, Response
  • X-Correlator, Request / Response
  • Authorization, Request
  • Content-Language, Response
  • Accept-Language, Request
• Add the Host header to Section 3.5 HTTP Headers Definition
• Add the following comment in Section 3.5:
  • "To avoid cluttering the CAMARA OAS (Swagger) definition files, the headers listed in this section must not be included, as it can be assumed that developers will already be familiar with their use"

[hdamker]

Can someone explain how the chapters "3.5 HTTP Headers Definition" and "9. Architecture Headers" relates to each other? Chapter 3.x looks for me more like a tutorial about HTTP (lacking references), but I have difficulties to read guidelines out of it. From the table in chapter 9 I can't read a guidance as the columns "required" and the new column "required on swagger" are not defined.

The complete document is never referring concrete to OpenAPI Spec nor has the term "swagger" as a potential synonym to OpenAPI Spec been used before chapter 9 in the document.

In general the document is lacking references, starting with the pictures in "2.1 Domain Driven Design" and ending with relevant important standards to be adhered (like OpenAPI Spec).

[eric-murray]

@hdamker
The API Design Guidelines were introduced in PR #96, with some additional but limited discussion in Issue #104. The relationship between Section 3.5 and Section 9 was never discussed, but I always interpreted Section 3.5 to be a list of "standard" or "well known" headers that a CAMARA API may or may not return (there is some guidance in there) and Section 9 to be "Here are some headers of particular importance to CAMARA and some guidelines on their use".

Now my interpretation of Section 9 is maybe challenged by the inclusion of Content-Language and Accept-Language in there, as I can't imagine any CAMARA API will ever use them. However, I could be wrong - maybe some API has great plans for these headers. Authorization is clearly essential, but I'm not sure it needs to be singled out in that section - just knowing that OAuth2 is in use tells the developer that an Authorization header is required.

So that leaves X-Correlator and X-Version. These are by no means "standard", so some description is required. My understanding was that these are optional to an implementation, but if an implementation does want the client to specify the transit tracking id, then they must call it X-Correlator, and if they want to return an API version number, they must call it X-Version. But additional description here would be useful.

But that is not the purpose of this issue or associated PR. The reason I originally raised this issue was to get an agreement on which headers should explicitly be included in OAS API definition files. And the answer is "None of the headers listed in the API Design Guidelines".

[shilpa-padgaonkar]

I agree with the proposal by @eric-murray

[hdamker]

But that is not the purpose of this issue or associated PR. The reason I originally raised this issue was to get an agreement on which headers should explicitly be included in OAS API definition files. And the answer is "None of the headers listed in the API Design Guidelines".

Fully agree here with you @eric-murray. It would be great to see a PR with the concrete changes that you have proposed above.

[RubenBG7]

Added comments and settings to the #161

[eric-murray]

Thanks @RubenBG7

I did some additional updates to the PR for Section 3.5, as discussed above.

A question on X-Version. I see this is marked as request header, so how is this intended to be used by the API caller? To identify the implementation of the API caller, a bit like User-Agent? Some additional explanation of this header would be useful.

[eric-murray]

Solved by PR #161