The Design of Web APIs | guh.me - gustavo's personal blog

1. What is API design?

Web APIs turn software into reusable bricks that can be used over a network with the HTTP protocol.
APIs are interfaces for developers who build the applications consuming them.
API design matters for all APIs—public or private.
Poorly designed APIs can be underused, misused, or not used at all, and even unsecure.
Designing a good API requires that you take the whole context of the application into consideration, not only the interface itself.

To be easy for consumers to understand and use, an API must be designed from the consumer’s perspective.
Designing an API from the provider’s perspective by bluntly exposing inner workings (data, code and business logic, software architecture, and human organization) inevitably leads to hard-to-understand and hard-to-use APIs.
A comprehensive and consumer-oriented API goals list is the strongest foundation for an API.
Identifying users, what they can do, how they do it, what they need to do it, and what they get in return is the key to building a comprehensive API goals list.

A REST API represents its goals with actions (HTTP methods) on resources (paths).
You must use portable data such as object, array, string, number, date, or boolean types when designing data.
A single API concept can have multiple data representations in different contexts.
If a parameter contains data that cannot be provided by consumers, you missed something.
Sometimes you will be frustrated or disappointed when designing APIs and having to strike a balance while facing design challenges—this is totally normal.

An API description format is a simple and structured way to describe and share a programming interface.
An API description document is a machine-readable document that can be used in numerous ways, including to generate API reference documentation.
You use an API description format only when designing the API’s programmable representation and data, and not before.
Always take advantage of an API description format’s documentation features. Explore the API description format’s documentation in depth so you can use it efficiently and, especially, to define reusable components where possible.

Any representation must be easily understandable by people and programs.
Any representation must be as informative as possible.
Error feedback must provide enough elements to understand and maybe fix the problem.
Success feedback must describe what has been done.
Goal flows can be optimized by adding data or goals to prevent errors.
Goal flows can be simplified by aggregating goals, but only if that makes sense from a functional perspective.

To create APIs whose operations can be guessed, consistently define conventions and follow common practices and standards.
Being consistent in your design not only makes your API easier to use, but also makes its design simpler.
Always check if your API needs to provide different representation and/or localization and internationalization features.
For each goal dealing with lists, consider whether paging, filtering, and sorting features will facilitate its use.
In order to guide consumers, provide as much as metadata as possible (like hypermedia links, for example).
Always check the underlying protocol and use its available features to make your API predictable, while taking care not to confuse users with complex or totally unused features.

Organize data properties by sorting them, naming them using patterns, or grouping them in data structures.
Categorize feedback and sort it by its importance.
Group goals by focusing on functionality and not representations; you can use API description format features or naming patterns (OpenAPI tags and URL prefixes for REST APIs).
Keep the number of properties and depth levels as low as possible in data structures.
Avoid creating does-it-all goals.
Split data structures, goals, and even APIs into smaller but functionally significant elements when possible.

API designers contribute heavily to API security by minimizing the attack surface.
An API should only expose and request what is really needed.
Consumers should only be allowed to use what they really need.
To ensure security, the design of an API must be done from the user’s perspective, keeping in mind what data is needed to control access.
Sensitive data and goals cover a wide range; exactly what should be considered sensitive might not be obvious and should be identified with the help of technical, security, business, and legal experts.
API designers must be aware of potential leaks due to the underlying protocol or architecture in order to fully secure the API design.

Each API evolution must be carefully designed in order to avoid breaking changes, which can cause problems not only on the consumer’s but also the provider’s side.
API designers might have to live with previous poor design choices in order to avoid introducing benevolent but breaking changes.
Depending on the context, breaking changes might be acceptable (for example, private APIs with consumers under the organization’s control).
API versioning is a design + implementation + product management matter.
Designing APIs with extensibility in mind eases the design of evolutions, lessens the risk of breaking changes, and favors API reusability.

API designers have a role to play in network communication efficiency.
The very first step of network optimization is at the protocol level, not the design level.
API granularity and adaptability have impacts on network efficiency.
Network efficiency problems can be a sign of missing or inadequate goals in the API.
API design optimizations must not be done at the expense of usability and reusability; providing different API layers can help to avoid such booby traps.

Unitary request/response, consumer-to-provider communication is not the only option; you can also design asynchronous goals, notify consumers of events, stream data, and process multiple elements in one call.
Designing APIs requires us to be aware of the consumers’ contexts, including their network environments, habits, and limitations.
Designing APIs requires us to carefully consider the provider’s limitations, to spot these earlier, and to solve problems without impacting the design (if possible) and adapting the design (if not).
Designing APIs requires us to ignore fashion and personal preferences. Just because you like or know a certain tool/design/practice doesn’t mean that it will be the ideal solution for all API design matters.

API designers must participate in the creation of different types of API documentation.
A detailed reference documentation is a good thing, but it is not enough. We must also create a user’s guide.
User guides must provide all needed information to use the API as a whole, including how to obtain credentials and tokens.
Leveraging an API description language such as the OpenAPI Specification can be of great help when creating documentation.
It is important to keep track of modifications in order to inform users of changes.
Creating documentation helps to test the API design.

Documentation is vital to designing, building, and validating APIs.
Consistency is impossible without API design guidelines and documentation.
Designing APIs must not be done alone: work with others on reviews and/or build a designers community.
API designers participate in the whole API lifecycle.
In order to design effective and useful APIs, API designers must challenge and deeply analyze the needs their APIs are intended to fulfill.