Something that all API’s need to consider (no matter how simple they are!) is how they will handle adding and upgrading functionality once someone gets a hold of it.
Sure, you could just wing it and rely on your test suite to give you some confidence in just rolling it out…but what about those weird and wonderful ways others may be leveraging your API? How will they cope with your update?
One approach that is often taken is to include the version number within your
endpoint routes - an example would be
this definitely works, it does create some issues with cache negotiation and
clients holding onto outdated links.
Cache negotiation pitfalls
A large portion of caching identifiers are based on URI unless configured
otherwise which means that
https://api.example.com/v1/users will have a
different cache key to
https://api.example.com/v2/users. While this is
desired behaviour you are potentially paying for the same cache data to be
served even though it could be identical and when you pay according to the
traffic offset by this service, it can quickly grow out of control. Should you
be lucky enough to have a self hosted service you have the additional overhead
of the same cached data being stored X times where X is the number of API
iterations are accessible.
People bookmarking and holding onto outdated links is a problem that is as old
as the internet itself and it probably won’t be going away any time soon. So
help yourself out by not creating more issues when
https://api.example.com/v1/... no longer works because version 1 of your API
has been deprecated and the newly released version is now located at
Now that you know the issues, what is the solution? You guessed it, the HTTP ‘Accept’ header.
Using the HTTP Accept header is relatively straight forward and looks a little something like this:
- vnd (as per RFC 4288) is the method of registering as a “vendor” and that you plan to interchange using this context.
- app_name is a field that identifies your application or product.
- version will contain the version number you wish to use to distinguish between iterations or releases. Common values are ‘v1’, ‘verison2’ or even ‘beta’.
- response_type covers what structure you plan to send the response as. E.g. ‘json’, ‘xml’, etc.
Using the HTTP Accept header
Now that you have a fair idea on why it benefits you to use the HTTP Accept header and what it looks like in the wild, it’s time to write some code to use it.
In this example an endpoint to return a user’s record has been setup. Unknown to the general public, a new field has been added to the API however while we are still within the testing phase we only want users who are a part of the beta program to see it.
To see the results all we need to do now is send a request to the endpoint specifying the correct HTTP ‘Accept’ header.
Now, let’s specify the ‘beta’ HTTP Accept header so that we can take advantage of that new field.