Version maintenance in REST APIs

REST based APIs provide significant advantages over other standards heavy interfaces like SOAP. REST makes it very easy to expose your business services to external world. It is not only simple data access, you can even encapsulate business logic in each API execution.

From a developer / architect standpoint, there are various areas that need to be looked into during the design phase. One extremely useful article I found is . It clearly talks about the things you should consider while building such interfaces. Remember that these are interfaces. Once built, you will find it very difficult to change the API contracts, no matter how compelling the reason could be. Hence it is important to get it right the first time.

One interesting challenge is version maintenance. You will eventually reach a situation where the API contract has to be changed – to support new features or fix some major issues. When that happens, how do you manage that change considering the widespread adoption of the API? Few suggestions:

  • Consider including version number in the API URL from the beginning
  • Set the expectations about backward compatibility and version number changes to the users.
  • Another smart way to handle versions is to make it user driven. In the API code, you will obviously have some logic to identify the user making API call. Now, use this information – it could be a user_id tag in URL or it could be one of the HTTP headers with username. Without changing the API contract, you can still support multiple versions. Users can nominate offline to what version of the API they want. At run time, based on user id, you can check in the mapping database and invoke the corresponding version code. This will keep the contract clean and user applications need do a code build and deploy just to change a version number.
  • Leave a Reply

    Fill in your details below or click an icon to log in: Logo

    You are commenting using your account. Log Out /  Change )

    Twitter picture

    You are commenting using your Twitter account. Log Out /  Change )

    Facebook photo

    You are commenting using your Facebook account. Log Out /  Change )

    Connecting to %s