75 lines
3.6 KiB
Markdown
75 lines
3.6 KiB
Markdown
---
|
|
name: api-contract-design
|
|
description: Use when designing or changing a REST, GraphQL, RPC, module, component, or service interface. Defines stable contracts, predictable errors, boundary validation, compatibility rules, and contract verification before implementation.
|
|
license: MIT
|
|
source: adapted from https://github.com/addyosmani/agent-skills/tree/main/skills/api-and-interface-design (MIT)
|
|
---
|
|
|
|
# API Contract Design
|
|
|
|
Design the contract before its implementation. Treat every observable public
|
|
behavior as something a consumer may depend on, including error shapes,
|
|
ordering, nullability, defaults, and timing-related semantics.
|
|
|
|
## Start from consumers and invariants
|
|
|
|
1. Identify every consumer and trust boundary.
|
|
2. Write representative requests/calls and exact successful and failing
|
|
responses.
|
|
3. State invariants: identity, authorization, idempotency, ordering,
|
|
pagination, concurrency, nullability, and retry behavior.
|
|
4. Define machine-readable input and output schemas before handler code.
|
|
5. Review the contract for misuse: make valid operations easy and invalid
|
|
states difficult or impossible to express.
|
|
|
|
Do not infer an API shape from its current implementation. Existing quirks may
|
|
be accidental; record which behaviors are intentional compatibility promises.
|
|
|
|
## Keep semantics predictable
|
|
|
|
- Use one naming convention across endpoints and fields.
|
|
- Use one structured error envelope with a stable machine code, safe human
|
|
message, and optional field details. Never expose stack traces or internals.
|
|
- Distinguish authentication, authorization, missing resources, validation,
|
|
conflicts, and server failures consistently.
|
|
- Validate untrusted input and third-party responses at system boundaries.
|
|
Once validated, let internal typed code rely on the contract instead of
|
|
scattering duplicate checks everywhere.
|
|
- Separate caller-supplied input types from stored/returned resource types.
|
|
- Paginate every collection that can grow; specify stable ordering, cursor or
|
|
page semantics, limits, and behavior when data changes between requests.
|
|
- State whether mutations are idempotent and how clients safely retry them.
|
|
- For concurrent updates, define conflict handling (version/ETag, transaction,
|
|
or explicit last-write-wins), rather than leaving races implicit.
|
|
|
|
## Evolve additively
|
|
|
|
Prefer optional fields, new endpoints, and new enum variants over renaming,
|
|
removing, or changing types. Before changing an existing interface:
|
|
|
|
1. Search all first-party callers, tests, fixtures, generated clients, docs,
|
|
and telemetry for actual usage.
|
|
2. Assume unknown external consumers may rely on undocumented observable
|
|
behavior.
|
|
3. Classify the change as additive, behavior-changing, or breaking.
|
|
4. For breaking changes, use a deprecation and migration plan; do not silently
|
|
maintain two indefinite implementations.
|
|
|
|
Be careful when adding enum variants: additions are compatible for producers
|
|
but can break consumers with exhaustive switches. Document an unknown/fallback
|
|
policy where independent deployment requires it.
|
|
|
|
## Verify the contract
|
|
|
|
- Add contract tests for success, each error class, boundary values, and
|
|
malformed third-party data.
|
|
- Confirm generated schema/client artifacts match the committed contract.
|
|
- Test retries and duplicate mutation requests where idempotency is promised.
|
|
- Test pagination across inserts/deletes and concurrency conflicts.
|
|
- Compare the implementation's observed responses with the documented schema.
|
|
- Ensure examples are executable and use the same field/error shapes as the
|
|
implementation.
|
|
|
|
Do not call an interface stable merely because its happy path works. Stability
|
|
means consumers can predict failures and evolve independently.
|