Designing Web APIs

Chapter 5. Design in Practice

Now that we’ve provided guidance on API paradigms, security, and best practices, it’s time for a hands-on, practical exercise in designing APIs. In this chapter, we take everything we covered in the first part of the book and use a fictitious example to explore different considerations.

In addition, we provide insights into how to create an effective design process so that you’ll be able to design APIs on your own for whatever your use case may be.

Throughout this section, we focus heavily on the user experience to anchor our design decisions. Today’s consumers are accustomed to excellent product experiences that suit their needs and lifestyle, not just products that get the job done. This high expectation for quality of experience goes beyond the products that people purchase. It extends to the apps that they use and the developer experience they expect when using APIs.

We might be building businesses and companies, but we don’t design APIs for ourselves. We design APIs for the systems receiving the data and, more importantly, for the people who build those systems. If those developers cannot use the data we’ve provided, we have ultimately failed to create a useful design.

In the following sections, we use two different scenarios to explore how to begin with a user-centric design process and how to get feedback along the way. There are many methodologies to design, and the following process is simply a framework from which to start. The most important ...