Using status codes and headers

HTTP enables communication between remote machines. Most developers only take care of the content part of the communication, that is the part that the user gets to see.

It is however equally important to engage intermediate machines in the conversation.

3 way communication

3 way communication

We do this by using HTTP status codes and headers.

A sample conversation for login would go something like this

#Request
GET     /protected/resource       HTTP/1.1        
Host:   www.example.org 
#Response
HTTP/1.1 401 Unauthorized
WWW-Authenticate:Basic realm="Protected Resources"    
Content-Type:application/json;charset=UTF-8
{
    "error":true,
    "message":"Unauthorized request"
}

In the above interaction we have informed the user that they are not allowed to make this request. But also we have told intermediary machines/services not to retry the request as well as provided the next steps.

If you we’re using a browser a basic auth login window would pop up on this response.

Do not go crazy with the realm value. It is meant to be opaque, that is your backend system can change without necessitating change of this value.

Next on the conversation, assuming the client has passed the server authentication challenge, is actually fetching the resource.

#Request
GET  /protected/resource HTTP/1.1
Host: www.example.org
Authorization:Basic cGhvdG9hcHAuMDAxOmJhc2ljYXV0aA==        
#Response
HTTP/1.1 200 OK
Vary:Authorization
Content-Type:application/json;charset-UTF8

{
    "error":false,
    "message":"This is my secret please keep it safe"
}

The server in this case confirmed the authorization header. Requests without it or with improper ones would have returned a 401 as we had seen earlier.

Now intermediary machines know that the request is authorized and can repeat the request say in case of network failure.

The Vary header informs the client machine on what other headers influence the request. So clients know to repeat this request an authorization header is required.

However by default GET requests are cached. This is ordinarily a good thing, the server is saved from the extra load of fulfilling requests and the client experiences less latency. In cases of protected resources this may not be ideal, we should consider limiting the amount of time the client and any intermediaries store the content.

This can be done by looping in the machines to the conversation once more as such

#Request
GET  /protected/resource HTTP/1.1
Host: www.example.org
Authorization:Basic cGhvdG9hcHAuMDAxOmJhc2ljYXV0aA==        
#Response
HTTP/1.1 200 OK
Cache-Control:max-age:3600,private
Vary:Authorization
Content-Type:application/json;charset-UTF8

{
    "error":false,
    "message":"This is my secret please keep it safe"
}

The cache control then ensures that this intermediaries do not store the data for more than a specified amount of time, in this case 3600 seconds or 1 hour. The private directive ensures that the cache is not shared or served to other clients.

If you liked this piece, sign up for our weekly newsletter.

Lets keep the conversation going.

Facebooktwittergoogle_plusredditpinterestlinkedinmail

Published by

jchencha

API Engineer