Versioning an API endpoint

Using an API is great, but what happens when your business already has clients, and your product communicates via an API, what should you do to evolve your API?

Whether it’s a server-to-server, or an app-to-server communication, the best way to evolve your APIs is to version them, this will help you to prevent breaking changes between the communication, and believe me, you don’t want to have angry clients knocking at your door.

Hope you don’t get this kind of clients… The best way so far is to do this:

Keep legacy (old) API as-is:

GET /api/user/{id}
POST /api/user/{id}

When having new changes, create your new endpoints as such:

Version 1

GET /api/v1/user/{id}
POST /api/v1/user/{id}

Version 2

GET /api/v2/user/{id}
POST /api/v2/user/{id}

Using dynamic versioning detection, if you are using a framework and home-made back-end 😎

GET /api(/v\d)?/user/{id}
POST /api(/v\d)?/user/{id}

What does (/v\d)? means:

  • ? means optional
  • \d means in regular expression digit

/v is the prefix for /v1, /v2, /v3 and so on…

Thus you will get /api/v{id}/people, where /v{id} as an optional pattern and id is any digit.

Learn to play with regex here: https://www.regextester.com/

With this combo you can have:

Infinite versioning, without breaking your legacy API

Request data from different versioning without tempering other endpoints.

When should you version your API?

  • When you have breaking changes;
  • It could happen when you have existing products communicating via your API, but you decide to upgrade the format, which is different from the existing one.

When you should NOT version your API?

  • It all depends on your business policy;
  • Maybe, due to security reasons, you might need to destroy the previous APIs to create a new one.
  • When you have missing fields, you can just add them in the existing API.

Stay stunned on BusyMind101 blog!

Photo by ThisIsEngineering from Pexels