API Versioning

SaaS On-premises 2.0

The 3scale API Management Platform allows you to do versioning. When you manage your API with 3scale, you have three ways to version your API correctly. The following methods are examples of how you could version your API within the 3scale Gateway, which provides some really nice extra features due to 3scale's architecture.


This guide will give you the basic instructions to implement an API versioning sysytem within 3scale.

Say you have an API for finding songs. Users can search for their favorite songs by different keywords: author, song title, etc. Assume you had an initial version (v1) of the API and you have now developed a new, improved version (v2).

The question this guide addresses is: how could you implement a version control workflow with 3scale?

The following describes the three most typical ways of doing it at 3scale:

  1. URL versioning
  2. Endpoint versioning
  3. Custom header versioning


You'll need to have done the basics of connecting your API to 3scale to proceed with this quickstart.

URL versioning

If you have different endpoints for searching songs (by artist, by song title, etc.), with URL versioning you would include the API version as part of the URI, like this:

  1. api.songs.com/v1/author
  2. api.songs.com/v2/author
  3. api.songs.com/v1/song
  4. api.songs.com/v2/song
  5. ...

Note that when you use this method, you should have planned - since v1 - that you were going to version your API.

The 3scale Gateway would then extract the endpoint and the version from the URI. This approach allows you to set up application plans for any version/endpoint combination. Then you can associate some metrics with those plans and endpoints, and you will be able to chart the usage for each endpoint on each version.

Check out the screen capture below to see how flexible 3scale is.

Now all you have to do is go to Dashboard > Integration on your 3scale Admin Portal and map your URI's to your metrics, as you can see here.

You will have two different versions of your API, each of them with different features enabled, and you will have full control and visibility on their usage.

If you now want to communicate to all of our users that they should move to the API v2, you can send all of them an internal note asking them to do so. Then you can monitor who makes the move and see how the activity on v1 decreases while the activity on v2 increases. By adding the metric in your authorization calls to 3scale, you can see how much overall traffic is hitting v1 vs. v2 endpoints and get an idea of when it's safe to deprecate v1.

If there are some users still using v1 after some time, you can filter out only those users to send another internal note, re-encouraging them to make the switch.

3scale also makes it super-easy to send that deprecation notice. Just follow these three steps:

  1. Go to the "Applications" tab and filter the list by the application plan that you want to send the deprecation note. Then click on the "Search" button
  2. Click on the multiselector to select all of them. When you do this, new options will be provided to perform bulk operations: "Send email", "Change Application Plan" and "Change State"
  3. Click on the "Send email" button and follow the steps to send a deprecation notice to those customers who are still under the obsolete version

The following image provides a visual reference:

Note that for each authrep call that's made to an endpoint, you authenticate only once but report twice (one for the endpoint and another one for the API version). Since the call will only be authenticated one time, there will be no double-billing. For each call you make to any endpoint of a specific API version, you will be aggregating the hits on a convenient metric named after the version number (V1, V2, ...), which you can use to compare full version traffic with each other.


Endpoint versioning

Here you would have the endpoint change for each version (api.cons.com/author_v1). The gateway extracts the endpoint and the version from the endpoint itself. This method – and the previous one too – allows the API provider to map external URLs to internal ones very easily. For instance:

The endpoint versioning method can only be performed with the on-premise deployment method, as it requires a URL rewrite that can easily be done using the LUA scripts that are provided as part of the on-premise configuration

api.songs.com/author_v1 could be re-written to internal.songs.com/search_by_author
api.songs.com/author_v2 could be re-written to internal.songs.com/author

Almost everything (mapping, application plans features, etc.) works exactly the same as in the previous method.

Custom header versioning

Here you would now use a header (i.e "x-api-version") instead of the URI to specify the version.

The gateway would then extract the endpoint from the path and the version from the header. Just as before, you can analyze and visualize any combination of path/version that you want. But this approach has several inconveniences, some of them regardless of the API management system you use (see this blog post on this topic) and some others related to how 3scale works:

  1. Just like the previous one, this method can only be applied to on-premise hosted APIs, as it requires some parsing/processing of the request headers to correctly route the authrep calls, and this kind of custom processing can only be done using Lua scripting.
  2. With this method, the fine-grained feature separation of the previous methods is much harder to achieve.
  3. One of the biggest advantages of using this methodology – and the main reason why some API providers choose it – is because the URL and endpoints of your customers will never change. When a developer wants to switch from one API version to another, they just have to change the header, and that's it – everything else works the same manner.