Designing Web APIs

Chapter 7. Managing Change

Good design is never frozen in time. Just because you made a great design today does not mean that it will continue to be good when change is afoot. Good APIs need to be able to adapt and change along with the evolution of your product or business.

Breaking changes are one of the common pitfalls of many APIs. In this chapter, we discuss how to approach change with an eye for consistency as well as how to ensure backward compatibility as your API evolves.

Expert Advice

An API should be consistent, clear, and well documented. Small inconsistencies around things like naming and URLs add up to a lot of confusion as your API ages. Because you want to keep from making breaking changes, you want to do your best to remain consistent but more importantly ensure that new additions are clear and obvious for integrators.

Kyle Daigle, director of ecosystem engineering at GitHub

Toward Consistency

Consistency is the hallmark of excellent experiences of any kind—APIs are no exception. Consistency builds trust. Trust is the foundation to creating a thriving developer ecosystem.

Here are some of the hallmarks of consistency:

• Developers are able to build a mental model of how to access data in your system.

• Response objects are formulated with strict types and meaningful names; that is, each model is the same regardless of the endpoint.

• Developers can use the same request patterns across a number of endpoints, which reduces the need for middleware and helps ...