Photo by Arif Riyanto on Unsplash

Real World Developer’s Problems: API Versioning

Jonathan Brizio
Apr 13, 2019 · 2 min read

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.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade