Selecting the correct API design pattern is essential for clarity, maintainability, and long-term platform health. These dimensions help determine when to use CRUD, Extended CRUD, Functional Resources (Commands), Query Models, Bulk, Async Jobs, Composite, Event-driven, or Streaming patterns.

2.1. Domain Fit

Domain fit evaluates how well a pattern aligns with the nature of the business capability.

  • For simple entities, CRUD is often appropriate.
  • For lifecycle transitions or workflow states, Extended CRUD aligns more naturally.
  • For domain actions or explicit business intent, use the Functional Resource Pattern (Commands).
  • For searching, filtering, reporting, use Query/RM patterns.
  • For background processes, use Async Jobs.

The goal is to choose the pattern that best expresses what the domain actually does, not what the database happens to store.

2.2. Consumer Experience

Consumer experience focuses on how intuitive the API is to its users.

Patterns influence:

  • Discoverability — Functional Resources make intent explicit (e.g., POST /orders/{id}/cancel).
  • Error clarity — Query patterns clarify input vs. output expectations.
  • Mental load — CRUD is simple for basic entities; workflows are clearer with Extended CRUD; actions are clearer with Functional Resources.

Use the pattern that minimizes ambiguity and aligns with how consumers think about the capability.

2.3. Operational Constraints

Operational constraints help identify whether the chosen pattern will work operationally.

Examples:

  • If an operation takes too long for a synchronous request → choose Async Job pattern, not CRUD or Functional Resource.
  • If the operation needs atomicity across multiple resources → Functional Resource or Bulk patterns may be more appropriate.
  • If the workload is search-heavy → Query pattern avoids performance bottlenecks created by naive CRUD listing.

Patterns should reinforce, not contradict, operational realities.

2.4. Lifecycle and Change

Lifecycle and change considerations focus on how the resource or operation will evolve.

Questions to ask:

  • Does the resource have a growing list of lifecycle transitions? → Prefer Extended CRUD or Functional Resources.
  • Will new domain actions emerge? → Avoid overloading CRUD; use Functional Resources.
  • Will read models evolve separately from write operations? → Introduce Query patterns.
  • Will workflows grow complex? → Preserve flexibility by choosing patterns that evolve cleanly.

Patterns chosen early can lower the cost of future change when thoughtfully aligned.

2.5. Governance, Security, and Access Control

Governance and security factors directly affect pattern selection.

  • Functional Resource endpoints allow fine-grained permissions (e.g., permission to “approve” without ability to “edit”).
  • Extended CRUD clarifies which transitions are legal and can be individually authorized.
  • CRUD is often too coarse-grained for sensitive workflows.
  • Query patterns must consider filter, projection, and pagination policies.
  • Async and event-driven patterns require verification, retries, and idempotency controls.

Patterns should reinforce security boundaries rather than weaken them.

2.6. Pattern Documentation Format

  • Pattern Name - Short, canonical pattern name (e.g., “Functional Resource Pattern”).

  • Also Known As - Alternate names or common references (e.g., “Commands Pattern”).

  • Primary Intent (What It Solves) - High-level purpose of the pattern, written in one clear sentence.

  • When to Use This Pattern - Bullet list of characteristics that signal good alignment with the pattern.

  • When NOT to Use This Pattern - Bullet list of anti-signals or misuse symptoms.

  • What This Pattern Looks Like - Description of the structural shape of endpoints using this pattern:

    • Common URI conventions
    • Expected HTTP methods
    • Typical request/response patterns
    • How state or side-effects are treated

  • Typical Examples - Representative endpoint examples developers can immediately recognize.

  • Common Anti-Patterns - Misuse symptoms that often emerge when the wrong pattern is chosen.

  • Governance Considerations - Authorization, lifecycle, versioning, and auditability implications.

  • Example OpenAPI Fragment - A small, self-contained OpenAPI snippet that demonstrates the canonical pattern shape.

2.7. How to Use the Patterns in Practice

During API design:

  • Start with the Pattern Overview Table to narrow down the likely patterns.
  • Use the decision tree to validate pattern choice.
  • Review the Pattern Card to ensure correct application of naming, structure, and semantics.

During reviews or governance checks:

  • Match each endpoint to a specific pattern.
  • Validate whether the endpoint actually follows that pattern (e.g., commands clearly labeled, CRUD limited to entity management).
  • Identify misuse (e.g., lifecycle transitions masquerading as PATCH calls).
  • Flag inconsistencies early to avoid costly downstream refactoring.

During onboarding of new teams:

  • Provide the Pattern Cards as part of API platform enablement.
  • Use them as discussion tools in ADDR workshops or domain alignment sessions.
  • Share them with product managers to help them articulate API needs more effectively.