| name | api-design |
| description | Design or evolve a backend API with explicit contracts, protocol semantics, compatibility, authorization boundaries, failure behavior, and consumer validation. |
API Design
Use when adding, changing, or reviewing an API or service interface owned by the backend.
Procedure
- Identify the consumers, the user or system capability being exposed, the current contract, and any compatibility constraints before choosing endpoint shapes.
- Model the operation in domain terms first. Do not let transport objects become the domain model by accident.
- Follow the repository's established protocol and conventions unless there is a concrete reason to change them. For HTTP, GraphQL, RPC, events, or another protocol, use that protocol's semantics rather than forcing REST conventions everywhere.
- Specify inputs, outputs, authentication context, authorization expectations, validation, error semantics, and observable side effects. Mark optionality and nullability explicitly.
- For collections or long-running operations, define pagination or streaming, ordering, filtering, idempotency, concurrency behavior, cancellation, and status retrieval where they matter.
- Define failure behavior deliberately. Separate client errors, authorization failures, conflicts, dependency failures, retryable failures, and unexpected server failures without leaking secrets or internal implementation details.
- Evaluate compatibility from the consumer's perspective. Treat field additions, default changes, ordering changes, error changes, and timing changes as potentially breaking when consumers can observe them.
- Record the contract using the project's normal mechanism such as OpenAPI, GraphQL schema, protobuf/IDL, typed interfaces, examples, or contract fixtures.
- Validate representative success, boundary, unauthorized, invalid, conflict, and dependency-failure cases. Use contract or consumer tests when the interface crosses a meaningful ownership boundary.
Decision rules
- Prefer a small coherent interface over exposing persistence models or internal implementation structure.
- Do not invent a new version merely to avoid thinking through compatibility, and do not assume an additive change is automatically safe.
- Make retry and idempotency semantics explicit for operations that can be repeated or partially fail.
- If the change creates a new trust boundary or authorization model, hand the security decision to
agency-security-engineer and implement the accepted design.
Quality gate
The API is ready when a consumer can implement against the contract without hidden assumptions, important failure and compatibility behavior is explicit, and executable validation proves the contract that matters.
