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.

  • Versioning in the URL structure – e.g., https://api.matt-rickard.com/v2/posts
  • Versioning with a URL query parameter – e.g., https://api.mattch-rickard/posts?v=2.1
  • Versioning with content negotiation – e.g., a Content Type: application/vnd.rickard.2.param+json header.
  • Versioning with other request headers – e.g., x-rickard-version:2023-01-01