Design and Build Great Web APIs

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