Great API design enables often good ground for great Developer eXperience. Even the API security starts from doing your API design thoroughly. The API security is one of the topics I need to dig deeper some day before the 100 Days DX series ends. But not today. This I started to wonder headers. That mysterious often hidden part of the stack. What exactly is supposed to be in headers and what should be in the body? I actually landed on the topic via API security.

I was reading security related information and headers was mentioned coouple of times due to authorization related things. Since I’m not a hardcore developer, discovering the world of headers was like “Wow” moment to me. That discovery some years ago resulted to more reading about the http protocol in general.

What are headers?

We are now talking about http headers to be more precise. And API here refers to REST API. One way to look at it in simple format is below. The image exemplifies the relation with headers and body.

To see that in “flesh” you can use multiple tools. I use command-line quite often so that’s what I do here too. With curl you can see just the headers of the API call by using --head option. Yeah, there’s probably a shorthand for that option but who cares. That will do the job. I call one of the Platform of Trust CORS enabled open APIs (Product API to list products from sandbox environment). I just want to see the headers:

curl --head -X GET "https://api-sandbox.oftrust.net/products/v1?offset=200&limit=400"

Great API Designer understands how headers work

Not much there to see though :) To make great API design you still need to understand the headers too, since some things are expected to be there and nowhere else. I can’t say that I have all-inclusive list of things that go to header and what not. Some things are still matters of opinion and depends on the case. Good example is versioning. Some say that it should be in the URL, but some say that it’s in the headers. You can see both but most commonly version is visible in the URL just for the sake of usability. But as you can see already we are not discussing what is in body and what is headers but also what is in URL.

Great API design is not just about followign the good patterns in endpoint and parameter names, clear error codes and using the HTTP methods. Great design takes the rest (pun unintended) into account.

Header types

There are 4 types of HTTP message headers:

  1. General Header These header fields have general applicability for both request and response messages.
  2. Client Request Header These header fields have applicability only for request messages.
  3. Server Response Header These header fields have applicability only for response messages.
  4. Entity Header These header fields define meta information about the entity-body or, if no BODY is present, about the resource identified by the request.

In the above example we had for example some server response headers like CORS related Access-Control-Allow-Origin: *.

What goes to headers then?

While the line is somewhat blurry, for me a rule of thumb is: data that your business logic works on should be in the body, metadata can/should be put in headers.

Another way of looking at it is: data which appears only in specific kinds of requests should be in the body while data which is handled consistently across the whole application should go into headers.

Yet another point of view is: can you imagine that a piece of data is handled globally, e.g. by a router/firewall rather than by your application? If yes, it should probably go in the headers rather than in the body.

Some examples of applying these rules would be:

One example of security related headers is the Bearer token. An example with the same API as above. To create a new product with Platform of Trust Product API, you must be authenticated and pass the Authorization Bearer token in the headers as part of the POST method call.

curl -i -X POST 
     -H "Authorization: Bearer <ACCESS_TOKEN>" 
     -H "Content-Type: application/json" 
     -d 
"{
    ...paylood
}" "https://api-sandbox.oftrust.net/products/v1"

Rate limiting is a hot topic

Needless to say that shit load of stuff happens at headers level. To really be a good REST API designer you really need to understand http protocol among other things.

One interesting thing is rate limiting. That is something API provider must almost always some how solve and communicate with the API consumer. Should that info be in the headers? If so, how should that be expressed? Network Working Group has a draft document of rate limiting headers edited by R. Polli (Full Stack Developer at Digital Transformation Team - Italian Government). I bumped into this draft by accident. A friend of mine Petteri Kivimäki (CTO at Nordic Institute for Interoperability Solutions (NIIS))happened to know Polli and tipped my off about his work couple of days ago.

Anyway the document contains thorough discussion on the topic and some examples. Lets look at one example. You can read the details from the draft your self.

Request:

  GET /items/123

Response:

  HTTP/1.1 200 Ok
  Content-Type: application/json
  RateLimit-Limit: 100
  Ratelimit-Remaining: 0
  Ratelimit-Reset: 50

  {"hello": "world"}

In the example RateLimit-Limit: 100 response header field indicates the request-quota associated to the client in the current time-window. Ratelimit-Remaining: 0 response header field indicates the remaining quota-units. Ratelimit-Reset: 50 The RateLimit-Reset response header field indicates either the number of seconds until the quota resets, or the timestamp when the quota resets.

In comparison for example Github has a bit different rate limiting headers:

HTTP/1.1 200 OK
Date: Mon, 01 Jul 2013 17:27:06 GMT
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 56
X-RateLimit-Reset: 1372700873

Difference is not huge. All rate limiting headers are prefixed with X-. To the application developer this change is still a hassle. If you use multiple APIS in your app (which is very common) you might need to handle headers differently. Wouldn’t it be great if all REST APIs would have exactly the same rate limiting headers?

Imgur API has yet a little different rate limiting headers:

X-RateLimit-UserLimit Total credits that can be allocated.

X-RateLimit-UserRemaining Total credits available.

X-RateLimit-UserReset Timestamp (unix epoch) for when the credits will be reset.

X-RateLimit-ClientLimit Total credits that can be allocated for the application in a day.

X-RateLimit-ClientRemaining Total credits remaining for the application in a day.

If you look at the APIs in the world you’ll find infinite number of rate limiting headers. I’d say that some standard format for basic rate limiting headers with REST APIs would be very welcome.

Some more to read from 100 Days DX