API Versioning

As the APIs/services evolves during the time, team has to make changes accordingly and making a change is not only about implementing the new functionality or making the changes in the existing ones, it’s about how to make it available to the consumer of that service without impacting the existing agreed contract. That’s the reason service versioning should not be ignored and decided beforehand while designing the architecture and should be part of API Design guideline document.

There are the following ways to add version number where each approach having its own benefits and drawbacks:
  • URL version: In this approach, version number is added to the URI for each resource like https://api.firstdecode.com/v3/orders/1
  • Query string versioning: Version number for a resource can be added in the form of Query String like https://api.firstdecode.com/orders/1?version=3. But remember that few browsers doesn’t cache response for requests that include a query string in URI which can degrade the performance that’s why it is not recommended.
  • Header versioning: In this approach, a version number can be added into the header string like adding “Custom-Header: api-version=3”.

Leave a Reply