The API design pattern catalog is designed to help developers and technical product managers (TPMs) quickly understand what each pattern is for, when it should be used, and how it differs from others. This serves as a map for the rest of the catalog and as a standalone reference for design reviews and governance activities.
3.1. Overview of All API Design Patterns
Below is a concise summary of each pattern. Each description highlights the core intent of the pattern — not implementation details.
| Pattern | Core Purpose | Typical Use Cases |
|---|---|---|
| CRUD (Resource-Oriented) | Manage simple entities with create/read/update/delete operations. | Customer records, product catalogs, configuration records. |
| Extended CRUD | Model lifecycle transitions or workflow steps that go beyond pure data editing. | Approvals, submissions, publishing flows, activation/deactivation. |
| Functional Resource | Expose explicit domain actions or intent-based operations. | Canceling orders, applying discounts, confirming transactions. |
| Query/Search Model | Provide read-optimized endpoints for searching, sorting, and filtering. | Dashboards, reporting, search interfaces, analytics. |
| Bulk / Batch / Import | Operate on multiple resources at once for efficiency and throughput. | Imports, migrations, mass updates, multi-item processing. |
| Long-Running & Asynchronous Operations | Handle operations that take time to complete using job/task resources. | Report generation, large file processing, background workflows. |
| Composite / Aggregator | Combine data from multiple backend sources into a single consumer-friendly response. | UI summaries, dashboards, mobile client APIs, partner overviews. |
| Event-Driven / Webhooks | Notify consumers of changes asynchronously through push-based updates. | Order status notifications, webhook integrations, event subscriptions. |
| Streaming APIs (SSE, WebSockets, gRPC Streaming) | Deliver real-time or continuous streams of data to clients. | Live updates, chat, IoT feeds, collaboration tools. |
| Pagination | Chunk large datasets into manageable pages to protect server and client resources. | Large collections, transaction logs, lists. |
| Filtering and Sorting | Allow clients to narrow and order collection results via query parameters. | Search interfaces, custom data views. |
| Singleton Resource | Manage resources with exactly one instance within a context. | User profiles, global settings, dashboards. |
| Polymorphic Schema | Dynamically adapt response/request shapes based on underlying types. | Heterogeneous collections, varied event payloads. |
| File Upload | Standardize binary data transfers with or without metadata. | Profile images, document attachments. |
| Cache Control | Optimize performance and reduce load via HTTP caching directives. | High-traffic static or slow-changing data. |
| Optimistic Locking | Prevent lost updates in concurrent scenarios using conditional requests. | Collaborative edits, configuration updates. |
| Pessimistic Locking | Exclusively lock resources to prevent modifications during external workflows. | Long transactions, strict human-in-the-loop edits. |
| Upsert | Create or update a resource in one call using a client-provided identifier. | Syncing external data, idempotent writes. |
| Draft Workflow Resource | Manage resources requiring partial saves and multi-stage validation. | Complex forms, CMS publishing flows. |
| Hypermedia-Driven Workflow | Guide clients through state transitions via server-provided links. | Self-navigating clients, complex state machines. |
| Lookup List | Offer name + descriptions of common lookup values, rather than enums. | Frequently changing lookup/enum lists. |
| Filter Collection by Identifier | Retrieve a specific batch of resources via explicit ID lists. | Resolving N+1 problems, shopping carts. |
| Master Detail | Defer high-resolution child records until requested after a summary query. | Time-series data, hierarchical dashboards. |
| Response Shaping and Inclusion | Empower clients to dictate the exact shape and nested inclusion of payloads. | Mobile data optimization, dynamic UI views. |
| Nested Resource Lifecycle | Scope child resources under a parent instance for strict ownership. | Domain composition (e.g., projects/tasks). |
| Change Request Workflow | Replace direct mutations with a formal proposal and approval lifecycle. | Maker-checker processes, regulated changes. |
| Intent-Based API Design | Shift design from data models to fulfilling specific goals to reduce cognitive load. | AI agents, autonomous LLM execution. |
| Intent as a Resource | Model long-running, multi-step transactions as trackable resources. | Asynchronous approvals, paused wizards. |
| Backend for Frontend (BFF) | Provide dedicated backend services optimized for specific client constraints. | Mobile vs. Web UI separation. |
| Backend for Context (BFC) | Shape and summarize API data specifically for an AI agent’s context window. | AI integration, legacy API bridging. |
3.2. Pattern Selection Checklist (Heuristics)
Use these quick decisions to drive pattern choice:
-
Is this a simple entity with no lifecycle? → Use CRUD (Resource-Oriented).
-
Is this entity moving through states? → Use Extended CRUD.
-
Is this a business action, decision, or intent? → Use Functional Resource Pattern.
-
Are you designing for an autonomous AI agent or LLM? → Use Intent-Based API Design to encapsulate multi-step logic and Backend for Context (BFC) to optimize token payloads.
-
Does a change require “maker-checker” approval before taking effect? → Use Change Request Workflow.
-
Is it a multi-step transaction that pauses for asynchronous user input? → Use the Workflow Resource pattern.
-
Is the operation read-heavy or analytics-oriented? → Use Query/Search Model.
-
Does the client need to fetch a specific batch of known IDs to avoid N+1 requests? → Use Filter Collection by Identifier.
-
Is the payload massive due to hierarchical or time-series data? → Use Master Detail to defer heavy child records.
-
Is it handling large volumes of writes/ingestion? → Use Bulk / Batch / Import.
-
Is it long-running or computationally heavy? → Use Long-Running & Asynchronous Operations.
-
Is the API serving highly tailored payloads to distinct client types (e.g., mobile vs. web)? → Use Backend for Frontend (BFF).
-
Is real-time or push-based interaction required? → Use Event-Driven / Webhooks or Streaming (SSE, WebSockets, gRPC Streaming) patterns.
Principle: Choose the pattern that best expresses intent and matches consumer use, domain structure, and operational behavior.
3.3. Pattern Relationships and Differentiators
This overview also helps clarify distinctions that developers often confuse:
- CRUD (Resource-Oriented) vs Extended CRUD – Data changes vs lifecycle transitions.
- Extended CRUD vs Change Request Workflow vs Workflow Resource – Extended CRUD handles immediate state transitions. Change Request Workflow proposes a mutation that pends approval before altering the core entity. A Workflow Resource manages a long-running, multi-step transaction that requires asynchronous client inputs before completion.
- Extended CRUD vs Functional Resource – State transitions vs domain actions with side-effects or decisions.
- Functional Resource vs Intent-Based API Design – While similar, Functional Resources typically expose single domain actions or calculations, whereas Intent-Based APIs encapsulate entire chains of orchestration specifically to prevent mid-transaction failures for AI agents and LLMs.
- Query/Search Model vs Filter Collection by Identifier vs Master Detail – Query/Search evaluates dynamic criteria (e.g.,
status=active). Filter by Identifier fetches an exact list of known IDs (e.g.,ids=1,4,5). Master Detail fetches high-level aggregates first, requiring a second call for granular data. - Composite / Aggregator vs Backend for Frontend (BFF) vs Backend for Context (BFC) – A Composite aggregates domains. A BFF optimizes aggregation specifically for diverse UI constraints (mobile vs. desktop). A BFC optimizes aggregation and filters PII specifically for an AI agent’s token-limited context window.
- Response Shaping vs Pagination / Filtering – Response Shaping dictates the horizontal shape and nested depth of a single entity. Pagination and Filtering dictate the vertical length and subset of a collection.
- Event-Driven / Webhooks vs Streaming (SSE, WebSockets, gRPC Streaming) – Push-based but discrete notifications vs continuous data flows.
- Long-Running & Asynchronous Operations vs Workflow Resource – Async Operations typically run unattended in the background (e.g., a report generation). A Workflow Resource represents an active state machine that often requires human intervention or sequential steps to proceed.
3.4 Pattern Comparison Matrix
This matrix helps compare patterns along key dimensions used in design reviews.
| Pattern | Primary Purpose | Typical URI Form | Latency Needs | Workflow? | Computation? | Volume | Output Shape | Best For |
|---|---|---|---|---|---|---|---|---|
| CRUD (Resource-Oriented) | Manage simple entities | /customers/{id} |
Low | No | No | Low–Medium | Full entity | Basic data mgmt |
| Extended CRUD | Lifecycle transitions | /articles/{id}/submit |
Low–Medium | Yes | No | Low–Medium | Updated entity | State machines |
| Functional Resource | Actions / computations | /estimate-tax |
Low–Medium | No | Yes | Low–High | Computed result | Business actions |
| Query/Search Model | Search & read models | /search-orders |
Low–Medium | No | No | High | Summary projections | Dashboards |
| Bulk / Batch / Import | Multi-item ingest | /customers/bulk-import |
Medium | No | No | High | Per-item results | Imports with partial success |
| Batch Import | Transactional ingest | /customers/batch-import |
Medium | No | No | High | Per-item validation | All-or-nothing imports |
| Long-Running & Asynchronous Operations | Long-running tasks | /report-jobs/{id} |
High | No | Yes | Medium | Job resource | Reports, analytics |
| Composite / Aggregator / BFF | Aggregated views | /customer-overview/{id} |
Medium | No | Maybe | Medium | View model | UI-optimized APIs |
| Event-Driven / Webhooks | Async notifications | POST callbackUrl |
N/A | No | No | Low–High | Event payload | Integrations |
| Streaming APIs (SSE, WebSockets, gRPC Streaming) | Real-time updates | /events/* or /ws/* |
Very Low | No | No | High | Event stream | Live UIs, telemetry |
| Pagination | Chunk datasets | ?page=2&limit=50 |
Low | No | No | High | Paginated List | Large collections |
| Filtering & Sorting | Narrow list results | ?status=active&sort=-1 |
Low | No | No | High | Filtered List | Search interfaces |
| Singleton Resource | Single entity instance | /user/profile |
Low | No | No | Low | Single entity | Settings, profiles |
| Polymorphic Schema | Handle varying shapes | /events |
Low | No | No | Low–Med | Mixed entities | Heterogeneous data |
| File Upload | Binary transfer | /users/1/avatar |
Low–Med | No | No | Med–High | Binary or status | Documents, media |
| Cache Control | Optimize reads | (Headers: ETag, etc) | Low | No | No | High | Cached entity | Read-heavy endpoints |
| Optimistic Locking | Concurrency control | If-Match: "etag" |
Low | No | No | Low | Updated entity | Collaborative edits |
| Pessimistic Locking | Exclusive lock | /orders/1/lock |
Low | Yes | No | Low | Status / Lock | Strict edits, long workflows |
| Upsert | Create/Update | PUT /items/{client_id} |
Low | No | No | Low–Med | Upserted entity | Idempotent syncs |
| Draft Workflow | Partial saves | /drafts/{id} |
Low | Yes | No | Low–Med | Draft entity | Multi-stage forms |
| Hypermedia Workflow | Server-guided flow | (JSON with _links) |
Low | Yes | No | Low–Med | Linked entity | Self-navigating UIs |
| Filter by Identifier | Batch fetch known IDs | /items?ids=1,2,3 |
Low | No | No | Low–Med | Item list | Cart loads, N+1 fixes |
| Master Detail | Progressive load | /summary, /detail |
Low | No | No | High | Summary / Detail | Dashboards, time-series |
| Response Shaping | Client payload shape | ?include=details |
Low | No | No | Med–High | Shaped entity | Mobile optimizations |
| Nested Lifecycle | Parent/child scope | /parents/1/children |
Low | No | No | Medium | Scoped entity | Strict composition |
| Change Request | Formal proposals | /requests/{id} |
Low–Med | Yes | No | Low | Request entity | Regulated workflows |
| Intent-Based Design | Goal execution | /reservations/change |
Low–Med | No | Yes | Low–Med | Outcome entity | AI/LLM integrations |
| Workflow Resource | Multi-step states | /returns/{id} |
Med–High | Yes | Maybe | Low | Workflow entity | Paused wizards, async steps |
| Backend for Context | AI payload optimization | /ai-context/summary |
Low–Med | No | Yes | Low–Med | AI Context | LLM prompt data |
| Backend for Frontend | UI payload optimization | /mobile-api/home |
Low–Med | No | Maybe | Low–Med | UI View Model | Client-specific APIs |