How to Version an API

Jan 21, 2023

Imagine you have a RESTful API that has been serving thousands of users. You've been maintaining the code, and now it's time to add a critical new feature – versioning. Often overlooked, API versioning is probably the most important part of the API infrastructure.

It's something that you should probably think about even at the earliest stages – not that all API endpoints and behavior need guarantees at that stage (and shouldn't). Still, versioning is easier earlier rather than later.  

A few considerations:

  • Will clients need to upgrade?
  • Will changes be backward compatible? Will v2 endpoints accept v1 requests?
  • Will the entire API be versioned or specific routes?
  • What happens when clients send a v2 request to a v1 endpoint? Vice versa?
  • Semantic versioning? Deprecation policy?

A few versioning strategies.