The Three Rules for Safely Modifying APIs

Design and Build Great Web APIs — by Mike Amundsen (89 / 127)

👈 Going Beyond Versioning | TOC | The Recommended Pattern for Testing for API C hanges 👉

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. In this section, we’ll focus on the interface and code side. We’ll deal with the deployment details in the next section (see ​The Process for Safely Deploying APIs​).

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…