Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News Don’t Version Your Web API

Don’t Version Your Web API

Leia em Português

This item in japanese

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