First of all best option is not to have any versions. That is rarely achieved with REST APIs, but more commonly we see different versions of those. I’m not going to discuss the version per se, but the migration from current version to new version. That is fascinating and exciting time for the API provider!

In traditional local applications, when some API elements (such as classes and methods) of a local API (an API without network interactions) change, the client may choose to continue using the old API if client developers do not want to upgrade. However, in the service paradigm, the service of an old API is often shut down after a certain period, and the client has tobe upgraded to adapt to the new API, otherwise the client will stop working. Thus, dealing with API evolution should be a much more serious problem in web applications than local applications.

Migration process contains issues which affects several slices in the 360 DX piechart

How much is changed in APIs then normally in version change? That is impossible to say accurately, but some indication can be found by analysing the popular APIs and changes in those. Li et al published 2013 a paper “How Does Web Service API Evolution Affect Clients?” which shows high numbers for changes. This is by the way a great article otherwise as well.

The high amount of changes indicates that API provider has packed great deal of breaking changes together before making the new version. This in turn will cause snowball effect on the consumer side. A lot of breaking changes in API equals high amount of changes in the client side. And if the API is a popular one, it will affect unimaginable amount of apps. The amount of developer time to be consumed in changes is massive.

Migration to new version with automated tools a wet dream and scholars have provided methods and tools for the purpose but majority of the migrations are done manually. Keep in mind that migration can be a painful moment for the API consumers and they need support. You don’t know exactly how they use your API. Even if it is not painful it is stressful.

If not handled promptly it can cause severe clashes between the provider and consumer.

Prepare for the crucial period

Helping your API customer in migrating to new version is part of great developer experience. Thus I see this as one of the worthy topics to cover here. Here’s a stereotypical model to do the launch of new API version and what often happens during the process and before it. It’s worth noting that migration process starts earlier on the provider side than on the consumer side.

As a API provider you need to keep the consumers aware of the changes in the APIs. That is part of good customer service and part of good developer experience. Before you launch new version of your API, you need prepare the documents and possible tools for API consumers. That might take time since you want to make sure guides work. Once you make “pre-flight” notice to API customers of the new version, your countdown to the big moment begins.

Another good practice is to use sunset header. The Sunset HTTP Header Field specification defines the Sunset HTTP response header field, which indicates that a URI is likely to become unresponsive at a specified point in the future. It also defines a sunset link relation type that allows linking to resources providing information about an upcoming resource or service sunset. Write a blog post in developer portal about the deprecation and how to stay tuned and what to follow.

Deprecation and sunset discussed can be seen to be different but related concepts. Deprecation means API version (or the entire API) will cease to exist. Sunset is the period towards the end of that version or API. Read more thorough explanation from Nordic APIs.

Sunset: Fri, 13 Nov 2020 11:11:11 GMT

Not all will see the headers, but some API consumers might have implemented alerts for sunset headers if such are encountered.

Written guides and documentation

When you are planning to release new version of your API, it’s a long process. You need to prepare for the switch thoroughly. One important thing is to provide migration guide. Doing version change without significant benefit for the consumer is something you should consider couple of times. Of course there might be some compelling internal reasons to do so, but your customer will not like that.

Make sure that your API documentation is pushing new consumers towards the new version. They might land to soon to be obsolete version API documentation and there should be guidance NOT to take it into use, but instead go for the new version. If you want to look at a good migration guide, Sendgrid has one. It is very common to provide comparison of the features in the migration guide.

That should give the developer hints which parts of the changes actually affects their app.

Provide safe methods to test migration

Your consumers might be happy if you provide sandbox API to work against. Testing the migration against production API is a bit hazardous. At Platform of Trust we have sandbox APIs available all the time so that is not a extra effort to us as API provider. If you provide sandbox API of the new version it must be there the same moment you launch the production version as well. Any of your clients might jump to new API right away. You could consider launching the sandbox version before you launch the production version.

Some providers might use the development version as the “sandbox API” for the migration period and then kill it.

Blackout testing

A blackout test can be defined as a planned, timeboxed event, when you turn off a certain API to help developers better understand the implications of the eventual retirement of that API. Twitter carried out their first blackout test in March 2013 to help application developers understand the impact the retirement would have on their applications a their users. This can also be seen as a dry run for all teams before the big day. Notice that blackout testing is significant break in service. Thus you should inform your clients about the test. Depending of your APIs terms of use that might require months in advance notice.

Track the migration

You should be tracking the soon to be obsolete version API usage with API management to see that the usage starts to go down. At the same time new version usage should be rising. If that is not happening you are loosing customers or your message of migration has not reached the API consumers. Put someone’s bonuses to count on the succesfull rollout of the new version. That normally motivates people to handle this delicate lifecycle status promptly.

After the migration period ends

Usually at the end of the migration period, previous version of the API becomes unresponsive and only way to consume your services is the new version, which is now the “current” version. Your API management should tell you “0 hits” for the old version the day sunset has been reached. There’s always consumers who say “What the hell! I did not see the change coming”. You need to prepare for that as well. Don’t count on the process to be fool proof.

Then you probably want to have a post mortem session of the migration internally to see what went well and how the process could be improved to minimize damage for customer and maximise customer satisfaction.


Some more to read from 100 Days DX