3 Pattern Catalog

Before diving into the full details of each pattern, this section provides a high-level view of the entire pattern landscape.

The goal is to help developers and 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 / BFF	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.

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.

• Is the operation read-heavy or analytics-oriented? → Use Query/Search Model.

• Is it handling large volumes? → Use Bulk / Batch / Import.

• Is it long-running or asynchronous? → Use Long-Running & Asynchronous Operations.

• Is the consumer asking for aggregated or UI-optimized data? → Use Composite / Aggregator / 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 Functional Resource – State transitions vs domain actions with side-effects or decisions.
• CRUD (Resource-Oriented) vs Query/Search Model – Data representation vs view models optimized for read operations.
• Composite / Aggregator / BFF – Domain aggregation vs client-experience optimization.
• Event-Driven / Webhooks vs Streaming (SSE, WebSockets, gRPC Streaming) – Push-based but discrete notifications vs continuous data flows.
• Long-Running & Asynchronous Operations vs Functional Resource – Long-running jobs vs synchronous business actions.

These differences prepare teams for the deeper dives in later sections.

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

3.5 Decision Tree Summary

                ┌───────────────── CRUD? (simple entity)
                │
           [Data mgmt?] ── Yes ───────────► CRUD
                │
                │ No
                ▼
         [Lifecycle?] ── Yes ─────────────► Extended CRUD
                │
                │ No
                ▼
      [Domain Action?] ── Yes ───────────► Functional Resource
                │
                │ No
                ▼
        [Search/Query?] ── Yes ──────────► Query/Search Model
                │
                │ No
                ▼
     [Many items at once?] ── Yes ───────► Bulk / Batch / Import
                │
                │ No
                ▼
 [Long-running operation?] ── Yes ───────► Async Jobs
                │
                │ No
                ▼
     [Aggregator/Composite?] ── Yes ─────► Composite/BFF
                │
                │ No
                ▼
   [Asynchronous notifications?] ── Yes ─► Event/Webhooks
                │
                │ No
                ▼
   [Real-time continuous updates?] ────► Streaming