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

Towards 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; ie each model is the same regardless of the endpoint and a “user” is always a user object
  • Developers can use the same object models or request patterns across a number of endpoints, which reduces the need for middleware and helps apps perform and scale. 
  • Requests fail predictably with meaningful errors

// Join a channel

channels.join({

  channel: "channel-name"

})

// Invite a user to a channel

channels.invite({

  channel: "C12345",

  user: "U23456"

})

This API endpoint takes a channel name.

This API endpoint takes a channel ID.

Comparison of Slack API methods ~2017: This small detail illustrates how inconsistency hurts developers. For a developer to be able to use both of these endpoints, they need to be able to store both the channel ID and channel name. But what if the channel ...

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