Versioning a REST API

1. The Problem

Evolving a REST API is a difficult problem – one for which many options are available. This article discusses 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 this the case, 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.

Therefore, this 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:

http://host/v1/users
http://host/v1/privileges

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

http://host/v2/users
http://host/v2/privileges

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. We’re going to version these media types 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"
    }
}

We can check out this ‘Custom Media Types for Rest APIs’ article for further information and examples regarding this subject.

What’s important to understand here is that the client makes no assumptions about the structure of the response beyond what’s 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 ARE 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 a 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. This is because they already understand and rely on the old format.

This is where Content Negotiation comes in. For such changes, we can add a new vendor MIME media type.

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. However, 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 kind 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. According to this, 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’s 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 too many good ones:

• • REST APIs must be hypertext-driven
  • API Evolution
  • Linking for a HTTP API
  • Compatibility Strategies