Sergey Nivens - Fotolia
Five tips for better API versioning and migration
Business needs change, and that often means APIs must change along with them. Here we examine five key strategies for avoiding disaster when API changes must occur.
API versioning and migration is an unfortunate fact of life, especially as application program interfaces become increasingly tied to ever-changing business priorities. However, if a few key steps are taken, making changes to your APIs doesn't have to be a disaster.
We talked with Inversoft CEO Brian Ponterelli, who shared five of his most important strategies he uses to minimize the risks that accompany API modifications.
1. Document your timeline
When an API is developed, it is likely that there is also a somewhat predictable schedule of planned patches or feature releases that may break compatibility. To avoid the wrath of unhappy consumers of your API, Ponterelli suggests that developers share a "calendar of events" that documents any changes that could affect those consumers.
"We just put it with release notes and documentation, and it works pretty well," Ponterelli said. "There are lots of ways, but as long as [the documentation] is somewhere, you're good."
2. Embrace semantic versioning
Semantic versioning is the de facto naming convention in the industry for patch releases, and, according to Ponterelli, using it is a critical way to make sure your API versioning doesn't get out of control. This formal standard, which has been adopted by most of the big players -- Oracle, Google -- provides a clear specification for version numbers as well as what compatibilities will be broken or left intact.
For your API consumers who understand semantic versioning -- and many do, Ponterelli said -- keeping track of changes will be easy. For those who are unfamiliar with it, there is easily accessible documentation out there about how it works.
3. Have a migration strategy and backwards compatibility adapter
When it comes time for a new version, developers are usually forced to break certain compatibilities. Unfortunately, your API consumers may rely heavily on those particular compatibilities, and Ponterelli warned that when users upgrade to find surprise breakages, it is not a pretty scenario.
Ponterelli advised that the best way around this issue is to create a clearly defined migration strategy with those consuming your API. This includes determining which compatibilities are essential to their operations, such as particular features or services that can't be allowed to fail, up front. If a full migration strategy can't be established, Ponterelli recommended that developers at least create a backwards compatibility adapter to help restore essential functions.
Ponterelli also suggested that developers start API versioning with their largest and slowest-moving customers, as smaller, more nimble companies are often more receptive to API changes. This allows you more time to deal with any potential problems and create any needed compatibility adapters.
4. Abstraction layers can help
In addition to creating managing compatibility, Ponterelli advised that developers add layers of abstractions that indicate the frequency of any API versioning. He referenced the APIs created by Amazon, which are abstracted into "fine-grain" APIs that undergo frequent modifications and "coarse-grain" APIs that go generally untouched.
By abstracting your APIs in this way, you can help provide your consumers a clearer understanding of how frequently they should expect changes to occur to the APIs they use and plan accordingly.
5. Consider a hybrid cloud approach
Ponterelli also noted that when provisioning APIs through the cloud, implementing a hybrid approach can help shield users from breakages. By keeping a certain number of critical resources and dependencies on premises, API users can continue to operate with their own version of whatever API they rely on. Otherwise, they may be forced to upgrade any time API versioning occurs, risking frustrating compatibility breakages.
This is especially important, Ponterelli said, when dealing with multi-tenant APIs that manage a large number of functions. And although it may be a little more costly to implement this hybrid approach, he insisted it's worth avoiding the API management headache. He also added that most users would much prefer to be behind a few versions than risk constant compatibility breakages.
