Design and Build Great Web APIs

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 ...