Chapter 2. API Versioning

The 3scale API Management Platform allows API versioning. You have one way to version your API correctly when you manage your API with 3scale v2.1. The following methods are examples of how you could version your API within the 3scale Gateway, which provides extra features due to 3scale’s architecture.

2.1. Goal

This guide is designed to give you enough information to implement an API versioning system within 3scale.

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

The following sections describe how to implement URL versioning using 3scale.

2.2. Prerequisites

Complete the basics of connecting your API to 3scale before using this quick start guide.

2.3. URL versioning

If you have different endpoints for searching songs (by artist, by song title, and so on), with URL versioning you would include the API version as part of the URI, for example:

  5. and so on

When you use URL versioning, 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. You can then associate metrics with those plans and endpoints, and you can chart the usage for each endpoint on each version.

The following screen capture shows 3scale’s flexibility.

Figure 2.1. Versioning Plan Feature

Versioning Plan Feature

The only thing left to do is go to Dashboard → Integration on your 3scale Admin Portal and map your URIs to your metrics, as shown in the following diagram.

Figure 2.2. Mapping URIs to metrics

Mapping URIs to metrics

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

If you want to communicate to all of your users that they should move to the API v2, you can send an internal note asking them to do so. 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 is safe to deprecate v1.

Figure 2.3. Versioning


If some users continue to use v1, you can filter out only those users to send another internal note about switching to v2.

3scale provides a three-step method for sending deprecation notices.

  1. Navigate to the Applications tab and filter the list by the application plan that you want to send the deprecation note and click Search.
  2. Click the multiselector to select all of the users for that particular version. New options display and allow you to perform bulk operations, such as Send email, Change Application Plan, and Change State.
  3. Click Send email 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.

Figure 2.4. Sending deprecation note

Sending deprecation note

For each authrep call that is made to an endpoint, you authenticate only once but report twice: once for the endpoint and once for the API version. There is no double-billing because the call can be authenticated only one time. For each call you make to any endpoint of a specific API version, you aggregate the hits on a convenient metric named after the version number (v1, v2, and so on), which you can use to compare full version traffic with each other.