Skip to main content

Deals You Can't Miss

1 Year Subscription

Versioning Approaches for RESTful APIs

When you develop your application for consumption by other applications, you do so by exposing your application's endpoints. This endpoint could emit XML or JSON data depending on whether SOAP or REST protocol is supported. As reality would have it, the domain keeps evolving keeping up with the demands of the consumer applications and the challenge is not all consumer applications want the same kind/structure of data or that they aren't keeping up with the pace of your evolution. So that brings the need for versioning your API endpoints, to meet the backward compatibility of at least some of your consumer applications. This leaves us with the question, as to how do we do versioning of our endpoints? And this post is about versioning the REST endpoints. 

There are 4 below ways in which you can version your REST APIs:

  • Option 1: URI Versioning
    https://mydomain.in/api/{api_version}/myresource
    https://mydomain.in/myTargetResource/myTargetService/{api_version}/
    https://api.plivo.com/v1/myresource
    https://api.twilio.com/api/2020.06.01/myresource
    https://instance_name.salesforce.com/services/data/v49.0/
  • Option 2: URL Query Request Parameter Versioning
    https://mydomain.in/api/myresource?version=1.0.0
  • Option 3: Custom Request Header Versioning
    https://mydomain.in/api/myresource
      headers[X-API-VERSION=1.0.0]
    https://mydomain.in/api/myresource
      headers[Api-Version=1.0.0]
    https://mydomain.in/api/myresource
      headers[MyCustomHeader=1.0.0] where,
    • Any headers beginning with X- are custom headers, and are not included in the HTTP spec..
    • There are a few interesting bits in the response headers. As expected, the Content-Type is application/json.
  • Option 4: Media Type Request Header Versioning
    https://mydomain.in/api/myresource
      headers[Accept: application/vnd.vendorprefix-v1.0.0+json]
    https://mydomain.in/api/myresource
      headers[Accept: application/vnd.mycompany+json;version=1.0.0]
    where,
    • Accept header in http advertises which content types, expressed as MIME types, the client is able to understand. Using content negotiation, the server then selects one of the proposals, uses it and informs the client of its choice with the Content-Type response header.
    • The vendor prefix (vnd.) indicates that it is custom for this vendor.
    • The +json indicates that it can be parsed as JSON, but the media type (defined by Content-Type header) should define further semantics on top of JSON.

There is no one approach that is always better than the others listed above. What works for you, depends on your context and in part is also, likely a subjective decision. That said there a few things to take into consideration during your discussions with your team and they are the following questions that can help you find your deciding factor:
  • Do you (or your consumer applications) see versions in URL as noise polluting it? If so, you can rule out options 1 and 2 in the list above.
  • Do you (or your consumer applications) see versions in custom Headers as noise polluting it? If so, you can rule out option 3 and potentially even option 4, if you are too finicky about it.
  • Which approach is the easiest to implement? An answer to this depends a lot on your choice of framework and architecture. Does your choice of framework support routing for sophisticated URL Versioning? 
  • How does it affect caching? For instance, header based versioning (options 3 and 4) affects URL based caching, because all the versions share same URL; you will have to change your caching strategy to accommodate request headers in them.
  • Do you document your API for publishing? What is its implication on the choice of tool for documentation to accommodate versioning strategy to how it gets published.

Different companies has taken different routes to REST API Versioning. Here are some examples of companies for each of the versioning strategy.

Additional Resources

My Popular Posts

Ten Commandments of Egoless Programming

We are nothing but the values we carry. All through my life thus far, I tried to influence people around me with the virtues I value. Thanks to some good reading habits I had inculcated, and the fortune of being in good community of peers and mentors alike, I managed to have read some real good books. This post is about the 10 commands of egoless programming in Weinberg's book. I shall explain the commandments based on my experience here. So very many decades ago, Gerald M. Weinberg authored  The Psychology of Computer Programming . In it, he listed The Ten Commandments of  Egoless Programming , which remains relevant even today for us as not just programmers but as team-members. Weinberg is regarded as a pioneer in taking a people-centric approach to computing, and his work endures as a good guide to intelligence, skill, teamwork, and problem-solving power of a developer. When they appear to inspire and instruct, we find that they can apply to just about every business area, and e

Should I buy refurbished laptop from Amazon?

This post is based on my experience with amazon.in and guess it to be true on all other platforms as well. At least you can check out and verify for these pointers before you make that decision to buy renewed/refurbished laptop on Amazon with your hard earned money. I see this question propping up in several forums and on many different occasions. In the recent past, I had my 5 year old dell laptop that gave up because its motherboard failed. One of the options that I had in my mind was to re-use the HDD and the 16GB DDR4 RAM of that old laptop in the one that I purchase next as secondary.  I had come to a conclusion that it is not worth buying a refurbished/renewed laptop at all. Why? For the following reasons, most of which I see as BIG #RedFlags: You got to remember that Amazon provides a platform for 3rd party sellers to sell their products as well. So in your search for refurbished laptops you wouldn’t want to choose some random 3rd party seller who Amazon doesn’t endorse. You cou

Multi-tenant Architectures

  Multi-tenancy Application Deployment Architecture could be modeled in 4 broad ways: Separate Apps & Separate Databases Shared Apps & Shared Databases Separate Apps & Shared Databases Shared Apps & Separate Databases There is no right or wrong here. It's about choice and consequence that you should consider taking into your business context and constraints. In this post I intend to jot down a some key points to keep in mind for each of these multi-tenant architecture. These are more of quick notes for my quick reference, a cheat-sheet of sorts when I have to make choices. And I guess this can come handy to you too in your wise decision making. Separate Apps & Separate Databases Easiest to implement from development and deployment stand-point. Just automate the deployment infrastructure for every tenant for quick set-up. Most expensive of all the models from infrastructure cost stand-point. Relatively longer deployment t