BT

InfoQ Homepage News Don’t Version Your Web API

Don’t Version Your Web API

Bookmarks

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:

http://api.equestrian.magic/v1/

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:

http://v1.api.equestrian.magic/

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:

application/vnd.equestrian.ponies.v1+xml

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
Style

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.

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

Community comments

  • Any ideas how to implement that?

    by Ilya M /

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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 /

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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

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

BT

Is your profile up-to-date? Please take a moment to review and update.

Note: If updating/changing your email, a validation request will be sent

Company name:
Company role:
Company size:
Country/Zone:
State/Province/Region:
You will be sent an email to validate the new email address. This pop-up will close itself in a few moments.