API Design Standards

Provides: Contract design decisions, error model conventions, pagination and idempotency patterns, and compatibility review criteria.

Quick Reference

Golden Rule: APIs are contracts; optimize for predictable clients

Default Stance:

• Contract first: name resources, schemas, and errors before writing code
• Be boring: use platform conventions over clever custom patterns
• Make failure explicit: stable error codes, actionable messages, retry guidance
• Evolve safely: additive changes first, breaking changes need migration paths

Never: leak storage internals, return unbounded lists, or overload one field with multiple meanings

Required Decisions

Settle these before implementation:

The audience decision drives the rest. A public contract cannot be changed on your schedule; an internal one can.

Contract Guidelines

Identifiers: Use stable identifiers. Do not expose auto-increment primary keys or internal storage paths unless you intend them to be part of the contract forever.

Field design: Prefer explicit typed fields over overloaded strings or untyped blobs. A status string that callers parse for substrings is a contract you cannot change.

Precision-sensitive types: Treat timestamps, time zones, money, and decimal precision as contract decisions, not implementation details. State the format (for example RFC 3339 with an explicit offset) and the unit (for example minor currency units as an integer).

Modeling: Shape the contract around user workflows, not around database tables. A response that mirrors your schema forces clients to reimplement your joins.

Errors: Separate validation failures from business conflicts. A malformed request and a request that conflicts with current state need different codes because clients handle them differently: one is a bug to fix, the other is a state to resolve. Return enough context to debug, and never expose secrets, stack traces, or internal hostnames.

Pagination

Keep every list endpoint bounded. An endpoint that returns all rows will eventually time out on your largest customer.

• Define a default page size and a maximum page size, and enforce both.
• Define sort stability. Pagination over a non-unique sort key skips and repeats rows as data changes; add a unique tiebreaker to the sort.
• Prefer cursor-based pagination when the underlying data changes while clients page through it. Offset pagination is acceptable for stable or small datasets.
• Document what happens when a cursor expires or becomes invalid.

Idempotency and Retries

Make mutations idempotent wherever retries are likely, which is any network call a client might time out on.

• Accept a client-supplied idempotency key on unsafe operations, and return the original result when the key repeats.
• State how long an idempotency key is honored.
• Document which status codes are safe to retry and which are not.
• Include retry guidance for rate limits: how long to wait, and whether to back off.

A client that cannot tell a timeout from a failure will retry a charge twice.

Compatibility

Additive changes are safe: new optional fields, new endpoints, new enum values in responses only if clients are documented to tolerate unknown values.

Breaking changes need a path: removing or renaming a field, tightening validation, changing a type, making an optional field required, or adding an enum value that clients must handle.

Before shipping a breaking change, decide the versioning mechanism, the deprecation window, how consumers will be notified, and how you will verify nobody is still using the old shape.

Webhooks and Events

Published events are a contract with weaker delivery guarantees, so they need more metadata than a synchronous response:

• Event ID so consumers can deduplicate redelivery.
• Timestamp for event time, distinct from delivery time.
• Schema version so consumers can handle multiple shapes during a migration.
• Replay strategy: whether consumers can request historical events, and over what window.

Assume at-least-once delivery and out-of-order arrival unless you have built stronger guarantees. Consumers must be able to process the same event twice safely.

Checklist

Before finalizing API work:

• The contract matches user workflows, not database tables
• Authorization is defined per operation and per tenant boundary
• Input validation and error responses are consistent across endpoints
• Pagination, filtering, and sorting semantics are documented, with a stable sort
• Idempotency and retry behavior are stated for every mutation
• Timestamp, time zone, money, and precision formats are specified
• Breaking-change risk and the versioning path are addressed
• Error responses expose no secrets, stack traces, or internal identifiers
• Tests cover success, validation, authorization, conflict, and retry cases

See also

• Load standards-security for authentication, tenancy, secrets, and PII handling.
• Load standards-database when the API shape depends on persistence or migrations.
• Load standards-testing for contract, integration, and compatibility tests.
• Load standards-documentation for public or partner API documentation.
• Load role-product-engineer when the contract is still being scoped.