Part 3
Contextual API design

Reading the first two parts of this book, you have learned to design APIs that make sense for consumers—ones that are easy to understand and easy to use without even thinking about it. Is that all you need to design APIs? Absolutely not. Thinking that an API designer’s job ends here would even be a terrible mistake. Stopping here would inevitably result in the creation of unfit and even dangerous APIs. Indeed, we designed APIs without much consideration to the whole context surrounding them:

• Is our design totally secure given the intended functions of the API and how it will be exposed to users?
• Will it actually be usable by, let’s say, a mobile application on a poor quality 3G network?
• Is our design actually the best one for our targeted consumers?
• Is it actually implementable upon our existing systems?
• Is our design so good that it does not need any documentation?
• Is our design totally consistent with all our other APIs?
• What if we want to update it once it has been pushed into production—can that be easily done?

All these questions must be answered. As API designers, we must take the whole context surrounding an API into account when designing it. Hopefully, you will learn to do so in the following chapters.

We’ll talk about security first. API security is not an afterthought delegated to someone else after design. An API must be secure by design to ensure that consumers, end users, and anyone or anything between them cannot do or see more than they are supposed to. This requires API designers to understand API security mechanisms, to know how to partition an API to facilitate access control, to include security concerns when designing from the consumers perspective, and, most importantly, to know how to handle sensitive material.

Then we’ll see that an API is a living thing; it will irremediably evolve. Designing API modifications requires extra care in order to avoid introducing breaking changes that will force all consumers to update their code to be able to use the updated API. Knowing how to do so is a key skill for API designers, but knowing how to design APIs that are evolvable from the ground up and lessening the risk of breaking changes when modified is even more important.

After that, we’ll talk about network constraints. A mobile application running on a smartphone over a 3G network doesn’t have the same constraints as an application running on a server on a local network. API designers must ensure that their design will actually be usable for the targeted consumers in their environment. They also must ensure that the design is actually efficient for all use cases, including edge cases which can, for example, imply more data or more calls.

We’ll also see that if network efficiency is a major constraint, it is only one among many. Designing APIs requires us to be aware of all constraints from both the consumer’s and also the provider’s side in order to create APIs that are totally usable and actually implementable.

In the last two chapters, you will discover that API designers have more to do than just designing APIs. We’ll talk about documentation. No matter how good a design, it must be documented in order to help not only consumers but also stakeholders understand it. An API must also be documented so the people in charge of its implementation can build it accurately. Just like security, API documentation should not be an afterthought. It is not something that can be completely delegated to someone else after the design; API designers must participate in it.

And finally, we’ll see how API designers can contribute to the growth of the organization’s API surface. By reviewing API design at various stages from various perspectives, the whole team can ensure that the resulting API will actually be what is expected. API designers have to participate in these reviews, even for APIs they are not working on. It is also fairly common to have many API designers working on many APIs in the same organization. This requires that all of them share what they do and how they do it—by creating design guidelines and building a community—in order to ensure a certain consistency and avoid everyone losing time reinventing the wheel.