Back to Home

What about Web API versioning?

Insights from a large-scale empirical study

20 October 2023

In Web API design, versioning is a critical concept that involves managing changes and updates to an API over time while maintaining compatibility with existing clients. The choice of versioning strategy can significantly impact API users and developers.

None can deny that till today there is a disagreement about 'what is the best way to version APIs?'. In 2014, Troy Hunt argued in his blog that API versioning is often done incorrectly, leading to unnecessary complexity and confusion.

But concretely, several years since the first Web API was published, what is the current state of practice? How do developers version their Web APIs? Do they follow the best practices? Or do they have their own versioning strategies?

Versioning in Vercel REST API: Vercel REST API adopts a unique versioning strategy where individual endpoints are versioned separately. Instead of incrementing the version with every change in response shapes, they employ straightforward v* version labels.

Versioning in GitHub REST API: Until November 2022, GitHub lacked an efficient versioning strategy for their REST API. Since the introduction of API v3 in 2011, the version identifier remained unchanged, regardless of the modifications made over the years.