Chapter 12: Modifying APIs

Design and Build Great Web APIs — by Mike Amundsen

While things might seem to be at a happy end, there are always more requests for added features. One of the challenges of a successful API is that people start thinking of new and creative ways to use it. And that almost always results in requests for modifications. Modifying the API is actually an important part of the overall lifecycle. In fact, the longest portion of an API’s life is spent in production. And the longer an API is in use, the more likely it is you’ll be asked to change it in some way.

Let’s explore the key steps to successfully implementing changes to your APIs after they’re released into production. Not surprisingly, these are the same steps we employed when creating the original APIs. First, model and design the requested changes and produce a machine-readable ALPS document. Second, employ the sketch, prototype, and build process to explore, confirm, and ultimately build your updated API. Last, use testing and security checks to validate your implementation before finally deploying the modified interface into production.

Going Beyond Versioning

Change is an inevitable part of APIs. It’s pretty unlikely that you’ll design, build, and deploy an API that’s “just right” and never needs to be updated. In fact, it’s a sign of a good API that people want to use it more often and come up with ways to make it even better. Popular APIs generate requests for changes. For that reason, we need to make changing APIs a regular part of our API practice.

The most common technique for handling API changes is to simply release a new, updated API in place of the old one. This is usually called “versioning your API.” It’s the most common, but it’s not the safest. If you’re not careful, you can release a new API that’s incompatible with existing uses. When this happens you are “breaking” current API clients — and that’s a bad thing.

Let’s take a look at few principles of safe and effective API. These principles lay the groundwork for the techniques recommended for properly changing APIs and for safely deploying these changes into production.

First, Do No Harm

Once your API is in production, it takes on a life of its own. When other applications are using your API, those applications become dependent on your API. That means you, as the author of the API, have a responsibility to all your API users. And one of the very first responsibilities is to “do no harm.” If you make a change to a running API that breaks one of your API consumers, you are not following the principles.

So, whatever you do, you need to be sure your changes won’t break an existing API consumer. One of the best ways to do this is to continue to write and perform extensive API tests.

Forking Your API

Sometimes, however, you’ll run into a situation where you must make a breaking change to a production API. For example, you might release an API that allows customers to update their personal information on your servers, and a year later the company decides that it will no longer allow customers to edit that data directly. When this happens, what you need to do is release a new API with the proper functionality and instruct all users of the existing API to update their applications to point to the new interface. While that happens, you need some time when both APIs are available in production.

This process is called “forking your API.” You create a new API based on the existing one and run both in production until everyone has updated their client applications. Along the way, you can do a few things to make it easy to migrate from the old release to the new one. For example, you can monitor the usage of the old release and identify key API users that may need assistance in upgrading to your newest release. You may even be able to provide “migration kits” — utilities and guides to help API consumers move from their current release to the more recent one. Finally, once all traffic to the old API has stopped, you can “turn off” the old API completely.

Knowing When to Say No

Finally, it’s important to know when to say no to requests for API changes. APIs take time and resources to build. And once released, they often take some time to “settle down.” You need to work out small bugs, people need to learn how to use the API, and operations may need to learn how to properly scale and manage the API in production. Once these elements are worked out, the API can run without much attention, providing benefits to everyone.

But as soon as you change the API, the whole cycle of design, build, and deploy starts up again, as does the predictable instability period you may experience when you release an update. As long as you keep changing the API, you’re likely to see some level of instability. Multiply these occasional periods of disruption by the 100s or 1,000s of APIs in your organization’s ecosystem, and you may be looking at a continual level of instability that can be quite frustrating.

For that reason, it’s important to know when you can just say no to API change requests. A good way to measure the potential value of an API change is to refer back to your initial API story and the early modeling work you completed for the initial API. Then ask yourself (and your team), “Will this new change help meet the initial purpose of the API design?” or “Do the proposed changes fit into the initial models used to create this API?” Sometimes the answer is no.

Instead of modifying an existing API, it may make more sense to create a new API that better matches the described need. If the new API eventually supersedes an existing API, you can close down the old one at some future date too.

The Three Rules for Safely Modifying APIs

As you’ve learned throughout the book, APIs are a collection of interface rules and promises. We design the interface to have certain features, like URLs, HTTP methods, arguments, return formats, and so forth, and then publish those interface rules as ALPS profiles, OpenAPI documents, and readable documentation. It’s this material that other developers will rely on when they want to use our API. That collection of information is our promise to API developers.

Once the API is released, we can’t break our promise to developers.

Two main areas need attention when updating an existing production API. The first is how you actually implement the change in the API service itself. This means how you handle the interface as well as the code. Once that work is done, you need to deal with how to deploy the change.

When modifying the API itself, we need to keep the “First, do no harm” principle in mind. We should not make any changes that cause existing API consumers any harm. That means no “breakage.” This principle applies specifically to the interface itself. But we also need to make sure we don’t change the code in a way that causes API consumers to see errors or “breaks” when they use our APIs.

From the interface point of view, you can rely on these three handy rules when contemplating changes to the API:

1. Take nothing away.
2. Don’t redefine things.
3. Make additions optional.

The Recommended Pattern for Testing for API Changes

Applying the three rules for modifying APIs starts at the design phase of your API update. It’s important you take the time to review all the requested changes before moving forward to make your API modifications. Then it’s important to implement those design changes faithfully. You also need to validate that your changes won’t break existing API consumers.

Validating API changes involves a few steps:

1. Asking yourself, “Who is using your API?”
2. Validating your API changes with existing tests
3. Confirming your API changes with new, stand-alone tests

The Process for Safely Deploying APIs

When you get to the point where you plan to release your API updates, you have one more opportunity to check for backward-compatibility issues and confirm that you’ve done all you can to eliminate “breakage” for your API consumer clients. That means you need to figure out the best way to deploy your updates into production. To cover all these details, we’ll need to focus on a number of things:

• Supporting reversibility
• Using side-by-side deployments
• Automatically routing traffic vs. waiting for clients
• Overwriting old API releases

Shutting Down an Existing API

As you create more and more APIs and deploy updates for the ones you have in production, eventually you’ll run into the need to shut down one or more of them. The process of “turning off” your API means addressing several important issues in order to ensure data integrity and operational safety, including these:

• Communicating the API shutdown
• Placing code in the public domain
• Publishing the interface design as open source
• Making consumer data recoverable
• Marking your API 410 GONE

And with that review, we’ve come full circle in our API journey. At this point, you should be armed with the skills and tools required to design and build the APIs you and your company need in order to meet your business’s and customer’s expectations.