1 What is API design?
Web APIs enable applications to communicate over a network, typically via HTTP, and provide a clean interface to capabilities without exposing internal implementation details. They power mobile apps, websites, and distributed systems, and can be private, partner, or public interfaces intended for use by teams beyond their creators. Because APIs are the programmable surface of systems, their design has outsized effects on developer productivity, system integrity and performance, user experience, and even revenue. This chapter establishes a clear, practical view of APIs as remote, HTTP-based interfaces to implementations that are created for others to use, and sets the stage for designing ones that are adaptable and intuitive.
Poor API design shows up as cryptic names and types, inconsistent identifiers and formats, vague error messages, missing pagination, leaky internals, and unclear security rules—leading to brittle client code, tight coupling, production failures, higher infrastructure costs, and security exposure. The consequences hit developers, architectures, and end users: slower delivery, crashes, data leaks, and churn. In contrast, well-designed APIs match real needs, hide inner workings, are predictable and interoperable, and remain stable as systems evolve. They unlock reuse, enable faster integrations, improve performance, reduce costs, and create a “just works” experience that accelerates time to value.
Design must be deliberate for every new API and every change, and it happens before coding within an iterative lifecycle that moves from defining needs to design, development, testing, deployment, and consumption. Effective design draws on three core roles—API designer, subject matter expert, and IT system expert—while engaging stakeholders such as consumers, security, and peers. The process starts by identifying capabilities in natural language, then shaping a programming interface (often REST) with coherent operations and data, describing it with a standard specification, and enriching artifacts such as mocks. A layered approach ensures the API does the right job and is versatile, remains user-friendly and interoperable, integrates constraints like security, efficiency, context, and change management, and improves continuously through guidelines, reusable components, and automation.
The Socnet web API exposed by the backend has operations that can be called by any kind of application over the internet. The Friends and Messages internal applications also expose web APIs that can be called over the local network.
When calling a web API, the consumer sends an HTTP request indicating what to do and the needed data. Once the request is processed, the server returns an HTTP response indicating how the processing went and the resulting data.
In a restaurant, we interact only with the waitperson without knowing what’s happening in the kitchen. An API acts similarly, hiding what’s happening in the implementation.
The terms internal, external, private, partner, or public API may need to be disambiguated so everyone involved understands each other.
The cryptically named Kitchen Radar has an unclear purpose and a complicated user interface that is cumbersome to use.
The Kitchen Radar’s user manual clarifies its purpose and explains how to operate it, but it doesn’t make it easier to use.
API design is an iterative activity distinct from deciding to create an API and implementing it.
This step-by-step and layered approach aims to help us design APIs in various contexts and facilitate our learning.
Summary
- Web application programming interfaces or web APIs are software interfaces that allow communication between applications over a network by leveraging the HTTP protocol.
- Web APIs enable communication between mobile or web applications and their backends and between server applications, can expose multiple operations, and can be consumed by multiple applications.
- Different types of web APIs exist; they leverage the HTTP protocol differently. This book focuses on REST APIs.
- A web API is an interface to an implementation and ideally conceals implementation details.
- A web API can be used by internal applications and developers (private API), selected partners (partner API), or anyone (public API). A private API can be exposed on the internet.
- Consider API design because it can positively or negatively impact developer productivity, security, infrastructure efficiency, costs, end-user experience, and an organization’s revenue.
- Design APIs that meet the user needs, hide inner workings, and are user-friendly, interoperable, and efficient.
- Design any new private, partner, or public API or modification of API.
- Design an API after deciding why to create it and before its implementation.
- Design private APIs to build skills via practice and design partner or public APIs more easily.
- Carefully consider API modifications to prevent unexpected crashes or silent behavior modifications.
- Design APIs collaboratively and iteratively.
- Leverage your or your colleague’s SME and IT expertise when designing an API.
- Discuss the design with the people who define the needs and consumers to ensure the API design matches expectations.
- Integrate, adapt, or refuse stakeholders' requests and feedback to design an API that satisfies all parties involved.
- Analyze needs and identify the required API capabilities to address them.
- Design the programming interface that represents the identified API capabilities.
- Align the choice of API type with capabilities and context.
- Build an API design reference kit starting with an API capabilities list and standard API description to support the design process and the following stages of the API lifecycle; enrich according to needs.
- Ensure your API design meets the needs, conceals inner workings, and is usable in different contexts.
- Ensure your API design is user-friendly and interoperable.
- Consider security, efficiency, contexts (subject matter, provider, or consumer), backward compatibility, and extensibility when designing an API.
- Establish a clear decision-making process for guiding research and ensuring confident and consistent API design choices.
- Create and continuously enrich an API design toolbox with API design guidelines, automated guidelines, and ready-to-use design components.
FAQ
What is a web API?
A web API is a remote, HTTP-based interface that lets applications communicate over a network. It exposes operations and data while hiding implementation details, so authorized consumers (internal teams, partners, or the public) can use it without knowing how it’s built.Why does API design matter?
Design determines how easy, safe, and efficient an API is to use. Good design boosts developer productivity, system performance, security, and user experience—ultimately improving business outcomes; poor design does the opposite, leading to bugs, fragility, outages, and lost revenue.Which API styles exist, and why focus on REST?
Common styles include REST, SOAP, GraphQL, and gRPC. The book emphasizes REST because it’s widely adopted and grounded in solid architectural principles, but many design principles apply to other styles as well.What do “private,” “partner,” and “public” APIs mean?
Private (internal) APIs are used within an organization; partner APIs are exposed to selected external parties; public APIs are open to anyone (often with registration). Clarifying these terms avoids confusion about exposure, security, and intended consumers.What are signs of poor API design and their consequences?
Red flags include cryptic names (like “sts”), inconsistent formats, missing pagination, leaky abstractions, vague errors, and misuse of HTTP. Consequences range from brittle client code and tight coupling to slow performance, crashes, security gaps, and higher costs.When should we design APIs?
Always design when creating a new API and when modifying an existing one. Do it after deciding an API is needed and before implementation, and iterate as you learn during development, testing, and early consumption.Who should be involved in API design?
An API designer, a subject matter expert (domain), and an IT system expert (technical constraints) are essential. Additional stakeholders—product/requirements owners, consumers, security experts, and peers—provide input that shapes and validates the design.What are the main steps of the API design process?
1) Identify capabilities from needs and use cases. 2) Design the programming interface (resources, operations likePOST /statuses, and data models). 3) Describe it in a standard spec (e.g., OpenAPI). 4) Enrich artifacts (constraints, examples, mocks) to support implementation and testing.
The Design of Web APIs, Second Edition ebook for free
