How to version a REST API that is dependent on the interface?

Question

Articles about REST APIs versioning tend to describe three versioning methods

1. To include the version in the URL: example.com/api/v1/myresource

2. To include the version in a header

3. To include the version in the content type

The application that I am building has two parts:

1. An interface that users can use to change settings that are stored in JSON format according to their needs.

2. An API that users can use to get resources and edit data.

The API is heavily dependent on the interface. In other words, if I changed the interface (e.g. renamed some JSON fields) the API could change its behaviour and even break.

All of those methods assume that the API version is not dependent of the interface since a user with any interface can use multiple API versions at the same time.

My question is how do you handle versions when your API is dependent on your interface?

The best solution that I came up with is to enable users to choose their version in the settings. By doing that I can serve the proper interface with its corresponding API method.

Best practices for API versioning? Described the three methods that I mentioned above. As far as I can tell they didn't talk about how to version an API that is dependent on the interface ( e.g. API v6 has to be used with interface v6 )

Answer 1

You can apply some strategies to minimize breaking changes by making your API more discoverable:

Hypermedia Constraint - Navigating with typed links and media types with versions: Helps you to move higher up the Richardson’s Maturity model (http://martinfowler.com/articles/richardsonMaturityModel.html) . The goal is to allow the origin server to change it’s mind on the URLs generated without breaking the client. Thus, no need hardcode the version number in your URL, just give one know URL and then link to the appropriate version if you really need a URL. This is also interesting if you design your operations tied to business concepts.

Semantic Versioning - You should only change the version of your API when you have "breaking changes" (see http://semver.org) which gives some interesting guidelines.

Updating contracts/data structures - For adding/removing JSON fields take a look also at Google Protocol Buffers > Language Guide > Updating a Message Type: there are some rules that you can apply to your media-types (and perhaps even link types) when it comes to exposing structured fields/data.

In the end it depends on your audience. Some may have some technical constraints and changes may really impact them and other are more agile and can adapt easily.

So, to get to your specific question: It seems that what you are describing works something like a "feature switch" see http://martinfowler.com/bliki/FeatureToggle.html . You enable a feature and the behavior changes. If you make your API discoverable (links appearing and disappearing based on what you enable/disable in what you call "interface") you can mitigate breaking changes using some guidelines as mentioned above. Modeling your API on your problem domain / business concepts makes it more stable than modelling just pure data (CRUD) operations. Kind of making use of a higher level of abstraction on your API (Business concepts vs low level data operations)

So, maybe you should rethink on what your users really want, for example integrating the options into one discoverable API (not just the entry point), where options are enables/disabled/configured with in the specific context.

Answer 2

You can choose the versioning method (include the version in the URL, include the version in a header or include the version in the content type) that is more appropriated for you.

When you a resource URL changes or a JSON property changes, you should consider releasing a new version of your API.

Sometimes you might have breaking changes from one version to another. So consider documenting those changes properly and also consider supporting a few different versions simultaneously. If a client performs a request using an unsupported version, consider giving them an appropriated error message.

---

For instance, have a look at the Facebook API changelog. From version to another, JSON properties names have changed, some of them have been deprecated and then removed and new properties have come in. Something similar happened to the API endpoints: some of them were renamed, deprecated then removed and new ones were added. The clients are expected to update their code to use the API. And an upgrade guide is always welcome.

Just to give you some insights, that's how Facebook supports multiple versions of their API:

Version Schedules

Each version is guaranteed to operate for at least two years. A version will no longer be usable two years after the date that the subsequent version is released.

So if API version 2.3 is released on March 25th, 2015 and API version 2.4 is released August 7th, 2015 then v2.3 would expire on August 7th, 2017, two years after the release of v2.4.

For APIs, once a version is no longer usable, any calls made to it will be defaulted to the next oldest usable version. Here's a timeline example: