Don’t Version Your Web API

| by Jan Stenberg Follow 23 Followers on Jul 20, 2016. Estimated reading time: 3 minutes |

A note to our readers: You asked so we have developed a set of features that allow you to reduce the noise: you can get email and web notifications for topics you are interested in. Learn more about our new features.

Versioning of Web APIs by adding a version to the URI or using versioned media types does not work on the open web. What we rather need are contracts that evolve with the changes we need, Sebastien Lambla claimed in a recent presentation, describing ways of avoiding the need to version.

For Lambla, consultant and advocate of the REST architectural style, a common reason for versioning of Web APIs is due to the contracts we use to avoid breaking clients. We want to allow clients and servers to be changed independently, and to be able to communicate API changes to client developers. For Lambla, versioning is basically a way to manage coupling, which in essence is about change control.

One way of versioning is to add the version to the URI:


One problem when the URI for a resource changes is that the resource can no longer be found with the old URI, unless redirects are used. Lambla emphasizes that the URI of a resource should never change, but with a new version it will have two different URIs, which normally means two different things, and it’s not possible to correlate them to each other.

An alternative is to add the version to the domain name:


Since URIs are opaque, in practice we have created a new system. With multiple systems and models, but still targeting the same data model, this becomes increasingly harder to maintain.

The third alternative is versioned media types, which Lambla believes is less common today on the web, but still quite common in enterprises. It’s based on content negotiation and adds a version number to the media type in Accept and Content-Type headers:


Lambla claims though that different versions are in reality also different resources and that using different media types on the same URI breaks the identification of resources. He refers to Roy Fielding for his claim:

We encourage resource owners to only use true content negotiation (without redirects) when the only difference between formats is mechanical in nature.

For Lambla, none of these versioning techniques work on the open web. What we really want is something that can evolve, using contracts that smoothly can evolve with needed changes. For Lambla this is a well understood problem, and refers to the web; with many millions of microservices it has been running for 25 years without too many problems and no versioning with the exception of HTTP.

The first pillar for evolvable contracts is backward compatibility. Lambla uses HTML as an example where there are lot of elements that we are discouraged from using, but they are still supported by clients since we can’t update all web sites in the world. The same principles should apply to an API; as it evolves it must still support old formats.

The second pillar is forward compatibility. To achieve this, you have to ignore the unknown or what is not understood. Lambla refers to CSS as an example where new attributes can be handled without problems. To achieve this, fall-back rules are used to handle unknown attributes, an important way to get extensibility points.

XML is still commonly used, and often with XML schemas. To support evolvability here we must be flexible in content and Lambla therefore strongly recommends against validating schemas in servers as well as in clients. Instead we should just find the elements and attributes we need and ignore the rest.

To avoid versioning, we need to continue with support of all features, but we can’t keep all changes in an API forever. Old features that are rarely used should be removed. To know when they can be removed we need to use metrics and measure usage. We can then decide that when usage falls below for example, 1%, the feature can be removed.

Rate this Article

Adoption Stage

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Any ideas how to implement that? by Ilya M

I just wonder if the approach described would be harder to implement and maintain than current classic versioning of APIs

Re: Any ideas how to implement that? by Pavel Gatilov

In one presentation about GraphQL, I heard an idea that GraphQL might allow this. With it, one can collect statistics on which fields and relations are used and which are not. I know it's not REST, but some people suggest that REST is outdated and GraphQL is the future.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

2 Discuss

Login to InfoQ to interact with what matters most to you.

Recover your password...


Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.


More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.


Stay up-to-date

Set up your notifications and don't miss out on content that matters to you