API Design Patterns & Best Practices

Design from the client workflow inward

Start with the business outcome the client needs, not the controller method or database table already in the server. A useful contract exposes domain meaning while leaving storage, queues, and service boundaries free to change.

1. 1

   Outcome

   Name the client intent

   State the result in client language: read one order, search orders, create one payment, or start one export.

2. 2

   Meaning

   Choose the resource boundary

   Give the durable noun a stable identity and use the method, path, and preconditions to express the allowed transition.

3. 3

   Capacity

   Bound request work

   Cap payloads, page size, fan-out, processing time, retries, and concurrency before the route reaches production scale.

4. 4

   Recovery

   Specify every outcome

   Define success, validation, authorization, conflict, limit, timeout, and dependency results with a safe next action.

Keep three boundaries separate

Lab: turn a workflow into a client contract

Choose a workflow, interface shape, completion promise, and collection policy. Watch the generated endpoint, client follow-up, response bound, and design findings change together. The goal is not a universal score; it is a contract whose consequences match the workload.

Route every request through explicit owners

An API is a boundary, not the whole system. The gateway can authenticate and apply coarse abuse controls, but the owning service must still authorize the resource, enforce business invariants, create the durable effect, and classify the result.

Give HTTP semantics one clear meaning

Use lowercase plural resource nouns and stable identifiers. Let standard methods carry their usual semantics so clients, caches, gateways, SDKs, and operators can reason about the route without private knowledge.

Make collection work finite

• Cap page size and response bytes; reject requests that ask the server to scan or return an unbounded collection.
• Prefer opaque cursors for large mutable collections. The cursor should bind ordering and continuation state without exposing storage internals.
• Define a stable sort with a unique tie-breaker so concurrent inserts do not make rows disappear or repeat between pages.
• Allowlist filters and operators. An arbitrary expression language can turn one valid request into an expensive full scan.
• State freshness and consistency. A fast list from a replica may lag a write that the client just completed.

Return errors that programs can act on

Use one machine-readable envelope with a stable error code, safe human message, request or trace ID, and optional field details. Do not expose stack traces, SQL, tokens, or secrets. Clients should branch on the stable code and status, not parse prose.

Separate the failure classes

• Invalid request: malformed syntax, unsupported content type, invalid field, or failed business validation. Point to the relevant field without echoing sensitive data.
• Unauthenticated or forbidden: distinguish missing or invalid identity from a caller that lacks permission for this resource and action.
• Conflict or stale state: identify version, uniqueness, or lifecycle conflicts and explain whether the client should refresh, choose again, or stop.
• Rate or capacity limit: return the policy scope and safe retry guidance. Do not invite every caller to retry at the same instant.
• Server or dependency failure: return a stable service code and correlation ID. Document whether a read may retry and how a write must reconcile.

Status codes provide a shared class, while application error codes carry stable domain meaning. For example, 409 Conflict may contain order_version_stale or idempotency_key_reused so the client knows which recovery path applies.

Publish one executable source of contract truth

An OpenAPI document can describe operations, parameters, schemas, security, examples, and reusable errors. Generate it from the implementation or validate both against the same schema in CI. A manually maintained document that drifts from runtime behavior creates a second, false API.

Test the boundary at several depths

1. Unit-test serializers, field validation, authorization decisions, idempotency fingerprints, and domain transitions.
2. Integration-test handlers with real databases and faithful dependency behavior, including deadlines and transaction failures.
3. Run provider and consumer contract tests against every supported client shape.
4. Diff the OpenAPI contract for removed fields, newly required inputs, enum changes, status changes, and altered retry semantics.
5. Inject lost responses, duplicate deliveries, stale preconditions, and dependency saturation before release.

Make non-idempotent writes recoverable

Network delivery is at-least-once unless the application proves otherwise. A client may send one request, receive no response, and still have the server commit the write. Retrying a payment, reservation, or message with a new identity can repeat the business effect.

An idempotency record should bind these values atomically at the owning service:

• Authenticated caller or tenant scope.
• Operation name and client-supplied key.
• Fingerprint of the normalized request body.
• In-progress or terminal operation state.
• Stored response or stable resource reference.
• Expiry long enough to cover the documented retry window.

The example rejects a reused key with a changed body and returns the first durable result for a valid replay. Production code must persist the key and side effect in one transactional boundary or reconcile them through an operation record.

Lab: recover an uncertain write without charging twice

Place a lost response before or after the durable write, choose a retry policy, and enable or remove the server's replay record. The trace updates write attempts, durable effects, duplicate charges, and the safe recovery decision.

Evolve the contract without surprising clients

Backward compatibility means a supported client can keep using documented behavior. JSON that still parses can nevertheless break when authorization, defaults, ordering, pagination, error codes, or retryability change.

Use URL major versions when routing and discoverability matter most. Header or media-type versions can keep URLs stable but are harder to inspect manually and easy to omit from tooling. Whichever strategy you choose, apply it consistently and publish the support policy.

Protect and operate the API as a product boundary

Enforce trust at the resource owner

• Keep credentials out of browser bundles, URLs, examples, and logs.
• Validate token issuer, audience, expiry, and signature, then authorize tenant, scope, ownership, operation, and current resource state.
• Use API keys for project identification only when that risk model is appropriate; a key alone is not user authorization.
• Apply rate, quota, concurrency, and payload limits by trusted identity. Avoid raw user IDs or keys as unbounded metric labels.
• Rotate signing keys and credentials with overlap, telemetry, and rollback rather than an instantaneous global cutover.

Measure the promise clients experience

Alert on user-visible symptoms and sustained capacity risk. Trace one correlation ID through the gateway, service, database or queue, dependency, and response. Redact sensitive fields and keep route templates bounded; raw paths with IDs create high-cardinality telemetry.

Continue with GraphQL, gRPC, and API Paradigms to compare other interface styles after the contract fundamentals are clear.

Check your API design decisions