about this book

The Design of Web APIs was written to help you design web APIs that do more than just cover expressed needs. This book will help you design outstanding web APIs that are usable by anyone in many different contexts, and those that are also secure, durable, evolvable, efficient, and implementable. It uncovers all aspects of web API design and gives a full overview of the web APIs ecosystem and how API designers can contribute to it.

Who should read this book

The Design of Web APIs is, obviously, for anyone who needs to design web APIs. They can be developers working on a backend for mobile applications or websites or needing to connect microservices together, or they can be product owners working on an API as a product, and everything in between. Actually, this book can be read by all people working on a project involving the creation of an API.

How this book is organized: a roadmap

This book has three parts that cover 13 chapters.

Part 1 teaches the most fundamental concepts and skills needed to design APIs.

Chapter 1 discusses what an API is, why its design matters, and what the elements of API design are.

Chapter 2 explains how to accurately determine an API’s purpose—its real goals—by focusing on the point of view of API users and the software consuming the API, and by avoiding the point of view of the organization and software exposing the API.

Chapter 3 introduces the HTTP protocol, REST APIs, and the REST architectural style. It teaches how to design a web programming interface (comprising resources, actions on resources, data, parameters, and responses) based on the identified goals.

Chapter 4 introduces the OpenAPI Specification and demonstrates how to describe an API in a structured and standard way using such an API description format.

Part 2 focuses on how to design don’t make me think APIs that will be easy to understand and easy to use.

Chapter 5 explains how to design straightforward data representations, error and success feedback, and flows of API calls that people will understand instantly and use easily.

Chapter 6 teaches how to design even more easy-to-understand and easy-to-use APIs, whose users (humans or machines) will be able to guess how APIs work, by making them consistent, adaptable, and discoverable.

Chapter 7 shows how to organize and size all aspects of APIs in order to keep them easy to understand and easy to use.

Part 3 shows that API designers must take into account the whole context surrounding an API and the whole context surrounding the API design process itself.

Chapter 8 describes API security and how to design secure APIs.

Chapter 9 teaches how to modify an API without unduly impacting its users, and when and how to version it. It also demonstrates how to design APIs that will be easy to evolve from the ground up.

Chapter 10 focuses on how to design network-efficient web APIs.

Chapter 11 exposes the whole context that API designers must take into account when designing APIs. It comprises adapting communication mechanisms (request/responses, asynchronous, events, and batch or bulk processing), evaluating and adapting to consumers' or providers' limitations, and choosing an adequate API style (resource-, function- or data-based).

Chapter 12 explains how API designers participate in the creation of different types of API documentation, taking advantage of an API description format like the OpenAPI Specification.

Chapter 13 shows how API designers can participate in the growing of many APIs by participating along the whole API lifecycle and across many APIs. It especially focuses on API design guidelines and API reviews.

This book should be read from cover to cover, each chapter in order. Each new chapter expands what has been learned in previous ones. That being said, once you have finished chapters 1, 2, and 3, you can jump to any chapter covering a topic that you need to investigate urgently.

About the code

This book contains many examples of source code both in numbered listings and in line with normal text. In both cases, source code is formatted in a fixed-width font like this to separate it from ordinary text. Sometimes code is also in bold to highlight code that has changed from previous steps in the chapter, such as when a new feature adds to an existing line of code.

In many cases, the original source code has been reformatted; we’ve added line breaks and reworked indentation to accommodate the available page space in the book. In rare cases, even this was not enough, and listings include line-continuation markers (➥). Additionally, comments in the source code have often been removed from the listings when the code is described in the text. Code annotations accompany many of the listings, highlighting important concepts.

Source code for the examples in this book is available for download from the publisher’s website at https://www.manning.com/books/the-design-of-web-apis.

liveBook discussion forum

Purchase of The Design of Web APIs includes free access to a private web forum run by Manning Publications where you can make comments about the book, ask technical questions, and receive help from the author and from other users. To access the forum, go to https://livebook.manning.com/book/the-design-of-everyday-apis/welcome/v-11/discussion. You can also learn more about Manning's forums and the rules of conduct at https://livebook.manning.com/#!/discussion.

Manning’s commitment to our readers is to provide a venue where a meaningful dialogue between individual readers and between readers and the author can take place. It is not a commitment to any specific amount of participation on the part of the author, whose contribution to the forum remains voluntary (and unpaid). We suggest you try asking the author some challenging questions lest his interest stray! The forum and the archives of previous discussions will be accessible from the publisher’s website as long as the book is in print.

Other online resources

There are so many online resources about APIs, but here are my two favorite ones:

• The API Developer Weekly Newsletter (https://apideveloperweekly.com/) is the best way to know what happens in the API world and to discover new sources of information about APIs.
• The Web API Events website (https://webapi.events/) will keep you updated about upcoming API conferences.