Real World Developer’s Problems: API Versioning
The backend world is fascinating and full of new things to discover.
In the beginning, you can feel domed with all the information, so the best way to understand is used commons examples that apply these concepts.
When you’re designing your backend, it is essential to have on mind some considerations. Think that your contract on the future would change and you need to maintain backward compatibility.
In some moment you API would be evolving, and you need to support the features they provide. Managing the impact of this can be quite a challenge when it threatens to break existing client integrations.
REST doesn’t specify any method of versioning, but the more common approaches are:
- Specify the version putting it on the URI:
https://api.example.com/v1/ - Using a custom request header:
Accept-version: v1 - Alternatively, adding to the HTTP Accept header
Accept: application/json; version=1
With these approaches, your challenge would be managing the entire code base with multiple versions of your resources. Content negotiation may let you prevent modify your entire collection of URLs, but you still have to deal with the all complexity of serving different versions of content.
Another approach can be to develop a consumer-driven contract that allows to consumer declare the data they are interested in consuming as part of a request. On this last case, you’re delegating the responsibility to the client.
Whatever approach you take, need to be consistent and active governance over the evolving contract.
Comment here what another approach you recommend or know it to recommend us.
