The new Certification Class of REST With Spring is out:


1. The Problem

Evolving a REST API is a difficult problem – one for which many options are available. This article discusses through some of these options.

2. What is in the Contract?

Before anything else, we need to answer one simple question: What is the Contract between the API and the Client?

2.1. URIs part of the Contract?

Let’s first consider the URI structure of the REST API – is that part of the contract? Should clients bookmark, hardcode and generally rely on URIs of the API?

If they would, then the interaction of the Client with the REST Service would no longer be driven by the Service itself, but by what Roy Fielding calls out-of-band information:

A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience…Failure here implies that out-of-band information is driving interaction instead of hypertext.

So clearly URIs are not part of the contract! The client should only know a single URI – the entry point to the API – all other URIs should be discovered while consuming the API.

2.2. Media Types part of the Contract?

What about the Media Type information used for the representations of Resources – are these part of the contract between the Client and the Service?

In order to successfully consume the API, the Client must have prior knowledge of these Media Types – in fact, the definition of these media types represents the entire contract, and is where the REST Service should focus the most:

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types.

So the Media Type definitions are part of the contract and should be prior knowledge for the client that consumes the API – this is where standardization comes in.

We now have a good idea of what the contract is, let’s move on to how to actually tackle the versioning problem.

3. High Level Options

Let’s now discuss the high level approaches to versioning the REST API:

  • URI Versioning – version the URI space using version indicators
  • Media Type Versioning – version the Representation of the Resource

When we introduce the version in the URI space, the Representations of Resources are considered immutable, so when changes need to be introduced in the API, a new URI space needs to be created.

For example, say an API publishes the following resources – users and privileges:


Now, let’s consider that a breaking change in the users API requires a second version to be introduced:


When we version the Media Type and extend the language, we go through Content Negotiation based on this header. The REST API would make use of custom vendor MIME media types instead of generic media types such as application/json. It is these media types that are going to be versioned instead of the URIs.

For example:

GET /users/3 HTTP/1.1
Accept: application/vnd.myname.v1+json
HTTP/1.1 200 OK
Content-Type: application/vnd.myname.v1+json
    "user": {
        "name": "John Smith"

What is important to understand here is that the client makes no assumptions about the structure of the response beyond what is defined in the media type. This is why generic media types are not ideal – these do not provide enough semantic information and force the client to use require additional hints to process the actual representation of the resource.

An exception to this is using some other way of uniquely identifying the semantics of the content – such as an XML schema.

4. Advantages and Disadvantages

Now that we have a clear concept of what is part of the Contract between the Client and the Service, as well as a high level overview of the options to version the API, let’s discuss the advantages and disadvantages of each approach.

First, introducing version identifiers in the URI leads to a very large URI footprint. This is due to the fact that any breaking change in any of the published APIs will introduce a whole new tree of representations for the entire API. Over time, this becomes a burden to maintain as well as a problem for the client – which now has more options to choose from.

Version identifiers in the URI is also severely inflexible – there is no way to simply evolve the API of a single Resource, or a small subset of the overall API. As we mentioned before, this is an all or nothing approach – if part of the API moves to the new version, then the entire API has to move along with it. This also makes upgrading clients from v1 to v2 a major undertaking – which leads to slower upgrades and much longer sunset periods for the old versions.

HTTP Caching is also a major concern when it comes to versioning.

From the perspective of proxy caches in the middle, each approach has advantages and disadvantages: if the URI is versioned, then the cache will need to keep multiple copies of each Resource – one for every version of the API. This puts load on the cache and decreases the cache hit rate, since different clients will use different versions. Also, some cache invalidation mechanisms will no longer work. If the media type is the one that is versioned, then both the Client and the Service need to support the Vary HTTP header to indicate that there are multiple versions being cached.

From the perspective of client caching however, the solution that versions the media type involves slightly more work than the one where URIs contain the version identifier. This is because it’s simply easier to cache something when its key is an URL than a media type.

Let’s end this section with defining some goals (straight out of API Evolution):

  • keep compatible changes out of names
  • avoid new major versions
  • makes changes backwards-compatible
  • think about forwards-compatibility

5. Possible Changes to the API

Next, let’s consider the types of changes to the REST API – these are introduced here:

  • representation format changes
  • resource changes

5.1. Adding to the Representation of a Resource

The format documentation of the media type should be designed with forward compatibility in mind; specifically – a client should ignore information that it doesn’t understand (which JSON does better than XML).

Now, adding information in the Representation of a resource will not break existing clients if these are correctly implemented.

To continue our earlier example, adding the amount in the representation of the user will not be a breaking change:

    "user": {
        "name": "John Smith", 
        "amount": "300"

5.2. Removing or changing an existing Representation

Removing, renaming or generally restructuring information in the design of existing representations is a breaking change for clients, because they already understand and rely on the old format.

This is where Content Negotiation comes in – for such changes, a new vendor MIME media type needs to be introduced.

Let’s continue with the previous example – say we want to break the name of the user into firstname and lastname:

GET /users/3 HTTP/1.1
Accept: application/vnd.myname.v2+json
HTTP/1.1 200 OK
Content-Type: application/vnd.myname.v2+json
    "user": {
        "firstname": "John", 
        "lastname": "Smith", 
        "amount": "300"

As such, this does represent an incompatible change for the Client – which will have to request the new Representation and understand the new semantics, but the URI space will remain stable and will not be affected.

5.3. Major Semantic Changes

These are changes in the meaning of the Resources, the relations between them or what the map to in the backend. This kinds of changes may require a new media type, or they may require publishing a new, sibling Resource next to the old one and making use of linking to point to it.

While this sounds like using version identifiers in the URI all over again, the important distinction is that the new Resource is published independently of any other Resources in the API and will not fork the entire API at the root.

The REST API should adhere to the HATEOAS constraint – most of the URIs should be DISCOVERED by Clients, not hardcoded. Changing such an URI should not be considered an incompatible change – the new URI can replace the old one and Clients will be able to re-discover the URI and still function.

It is worth noting however that, while using version identifiers in the URI is problematic for all of these reasons, it is not un-RESTful in any way.

6. Conclusion

This article tried to provide an overview of the very diverse and difficult problem of evolving a REST Service. We discussed the two common solutions, advantages and disadvantages of each one, and ways to reason about these approaches in the context of REST. The article concludes by making the case for the second solution – versioning the media types, while examining the possible changes to a RESTful API.

7. Further Reading

Usually these reading resources are linked throughout the article, but in these case, there are simply to many good ones:

Go deeper into building a REST API with Spring:


Sort by:   newest | oldest | most voted

Whats wrong about setting an additional header like “X-apiversion” ?

Abdullah Battal

Seems legit to me.

Eugen Paraschiv

There are many problems with using your own custom request header to do versioning – here’s just a few:
– caching won’t work at all – which is huge red flag
– the resource is now identified by more than the URI
Here’s a more in-depth discussion from Mark Nottingham – who’s working on the HTTP2 spec.
Hope that helps. Cheers.


Interesting article. With the hateoas links in a response how should you indicate that a versioned media type should be sent n the request?
I suppose that if the client was smart enough to supply it they will do it for the next request.

Eugen Paraschiv

The media types are the only part that the client needs to have prior knowledge of. Check out the part about media types above.
Thanks. Eugen.


you could also use the following MIME type: “application/vnd.myname+json; version=2”