Patterns for sustainable API-design

This post will outline a few ideas and patterns essential to sustainable API design.

APIs are more than just communication interfaces between systems and machines; they also need to facilitate communication between humans. APIs are often created outside the teams consuming them and thus need to follow the principle of least astonishment (POLA).

Sustainable APIs use the HTTP verbs correctly, has consistent error handling, and, in the spirit of domain-driven design, words mean what they do in the domain. The URLs are human-readable and understandable, even without a client library, helping the front-enders and other consumers to iterate quickly and confidently.

They are also documented in a machine- and human-readable way, utilizing existing ecosystems like OpenAPI, Swagger, and the like. Consumers should be able to quickly consume our APIs using their programming language and tech stack of choice.

Sustainable APIs are not alone; they are monitored. They have a team who care for them, watching their use, performance and availability. APIs need not only to provide the correct response but also to do so timely and consistently. Logging is not enough; the team must act proactively if something is amiss. Consumers or users should never be the ones to alert the team first. The API must tell us itself.

Sustainable APIs don't have outages, but when they do, their status is communicated honestly and understandably to consumers. Sharing information is critical, both to affected consumers and also to others inside our organization. It can be hard to know who needs to know what, so oversharing is caring. And when the problem is fixed, a proper post-mortem and newly added automated test will ensure it doesn't happen the same way again.

Sustainable APIs can be consumed at any time, and as long as an API has consumers, it must maintain backward compatibility.

This is simple; it needs only to satisfy two constraints:

1. A new API version must be able to read existing clients requests
2. Old clients must be able to read responses from the new API

Breaking one or both of these leaves us with a different API or, at the very least, a new version. The old API should, in either case then, remain as long as needed to avoid breaking clients. Technologies like GraphQL may help, but we still need to be careful. Identical words must still mean the same things; if not, woe to the consumers.

These three points are not sufficient for sustainable API design, but they are necessary. APIs are part of our system's UX, and we must care for them. We need to empathise with our consumers, make our APIs understandable, monitor their performance, and, of course, never break user space.