Going Beyond Versioning
Design and Build Great Web APIs — by Mike Amundsen (88 / 127)
👈 Chapter 12 Modifying APIs | TOC | The Three Rules for Safely Mo difying APIs 👉
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.
In the next section, we’ll look at a few principles of safe and effective API changes:
- First, do no harm.
- Fork your API.
- Know when to say no.
These principles lay the groundwork for the techniques I recommend for properly changing APIs and for safely deploying these changes into production.
