O'Reilly logo

Designing Web APIs by Amir Shevat, Saurabh Sahni, Brenda Jin

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

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.

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

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required