These are guides for API design. These guides are grouped by topic and are intended to quickly make you productive in the design of APIs.
API Design Patterns
1. Why API Design Patterns Matter
Explore why we should think of API design in terms of applying design patterns and the value they provide.
2. Evaluation Dimensions for Pattern Selection
The dimensions for selecting the correct API design pattern is essential for clarity, maintainability, and long-term platform health.
3. The Pattern Catalog Landscape
A quick-reference of all patterns and the pattern card format.
4. Pattern: Resource-Oriented CRUD
The CRUD (Create, Read, Update, Delete) pattern is often the first interaction style developers encounter, managing the create, read, update, and delete lifecycle of a resource.
5. Pattern: Extended CRUD
The Extended CRUD pattern is used when a resource has a lifecycle that goes beyond simple create/read/update/delete, while avoiding the overloading of PATCH or PUT with magic “status flips” that can be confusing and difficult to audit.
6. Pattern: Functional Resource
The Functional Resource pattern exposes command-style, compute-style, or decision-style operations that do not represent a resource lifecycle.
7. Pattern: Query/Search Model
The Query / Search Model pattern is used when consumers need flexible, read-only access to data via search, filtering, sorting, and projections — often beyond what a simple CRUD GET /resource can support.
8. Pattern: Bulk/ Batch / Import Operations
The Bulk / Batch / Import Operations Pattern is used to process multiple items in a single API request, allowing servers to efficiently create, update, or validate large sets of data.
9. Pattern: Long-Running & Asynchronous Operations
The Long-Running & Asynchronous Operations pattern is used when an operation cannot reasonably complete within a single synchronous HTTP request without blocking until work is done.
10. Pattern: Composite / Aggregator / BFF Pattern
The Composite / Aggregator / BFF (Backend-for-Frontend) pattern is used when a client needs data that spans multiple backend services or resources, and you want to present it through a single, tailored API endpoint that manages one or more API calls behind-the-scenes.
11. Pattern: Event-Driven APIs & Webhooks
The Event-Driven APIs & Webhooks pattern is used when servers need to notify consumers of changes asynchronously through a subscription endpoint, rather than requiring clients to poll for updates.
12. Pattern: Streaming APIs (SSE, WebSockets, gRPC Streaming)
The Streaming API pattern is used when clients need continuous, real-time updates without polling. Instead of repeatedly calling GET /resource for updates, clients maintain a persistent connection over which the server can push events and notifications.
13. Pattern: Pagination
Pagination prevents large result sets from overwhelming clients and servers. Without pagination, servers take longer to query and build their response.
14. Pattern: Filtering and Sorting
The Filtering and sorting pattern helps clients to retrieve resources based upon specific criteria and sort order.