The Three Rules for Safely Modifying APIs

Overview

As we’ve learned throughout the course, APIs are a collection of interface rules and promises. We design the interface to have certain features, such as URLs, HTTP methods, arguments, return formats, and so on. We can then publish those interface rules as ALPS profiles, OpenAPI documents, and readable documentation. It’s this material that other developers 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 we actually implement the change to the API service itself. This means how we handle the interface as well as the code. Once that work is done, we need to deal with how to deploy the change.

When modifying the API itself, we need to keep the do no harm principle in mind. We should not make any changes that cause existing API consumers any harm. In other words, 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, we can rely on these three handy rules when contemplating changes to the API:

• Take nothing away
• Don’t redefine things
• Make additions optional