Chapter 2. API Versioning
The 3scale API Management Platform allows API versioning. You have three ways to version your API correctly when you manage your API with 3scale. 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 the three most typical ways of implementing an APR versioning system using 3scale:
- URL versioning
- Endpoint versioning
- Custom header versioning
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:
- api.songs.com/v1/songwriter
- api.songs.com/v2/songwriter
- api.songs.com/v1/song
- api.songs.com/v2/song
- and so on
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. 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
The only thing left to do is go to Dashboard
Figure 2.2. 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.
- Navigate to the Applications tab and filter the list by the application plan that you want to send the deprecation note and click Search.
- 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.
- 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
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.
2.4. Endpoint versioning
You have the endpoint change for each version (api.cons.com/author_v1) with endpoint versioning. The gateway extracts the endpoint and the version from the endpoint itself. This method , as well as the previous method, allows the API provider to map external URLs to internal ones.
The endpoint versioning method can only be performed with the on-premise deployment method as it requires a URL rewrite using the LUA scripts that are provided as part of the on-premise configuration.
| EXTERNAL | INTERNAL | |
| api.songs.com/songwriter_v1 | could be rewritten to | internal.songs.com/search_by_songwriter |
| api.songs.com/songwriter_v2 | could be rewritten to | internal.songs.com/songwriter |
Almost everything (mapping, application plans features, and so on.) works exactly the same as in the previous method.
2.5. Custom header versioning
With custom header versioning, you use a header (that is, "x-api-version") instead of the URI to specify the version.
The gateway then extracts 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. This approach has several inconveniences, regardless of the API management system you use. See API versioning methods, a brief reference for more information. Here are a few pointers on how 3scale works.
- Just like the previous method, custom header versioning can only be applied to on-premise hosted APIs because it requires some parsing/processing of the request headers to correctly route the authrep calls. This type of custom processing can only be done using Lua scripting.
- With this method, the fine-grained feature separation of the previous methods is much harder to achieve.
- One of the biggest advantages of using this methodology, and the main reason 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 only have to change the header. Everything else works the same.
