API Design
Start from consumer tasks and domain semantics rather than transport mechanics.
Contract
- Define resources/actions, inputs, outputs, invariants, ownership, authorization, and side effects.
- Specify validation, error categories, retryability, timeouts, cancellation, and partial failure.
- Use idempotency for retryable mutations and define concurrency/conflict semantics.
- Design pagination, filtering, ordering, field selection, limits, and consistency explicitly.
- Bound payloads and document rate limits, quotas, and abuse controls.
- Use stable names and additive evolution; document deprecation, versioning, and migration for breaking changes.
Provide representative success and failure examples plus contract tests. For event APIs, also define delivery guarantees, ordering, duplication, schema evolution, replay, and dead-letter handling.
1---2name: api-design3description: Design or review stable APIs with explicit contracts, errors, authorization, idempotency, pagination, compatibility, and evolution.4---56# API Design78Start from consumer tasks and domain semantics rather than transport mechanics.910## Contract1112- Define resources/actions, inputs, outputs, invariants, ownership, authorization, and side effects.13- Specify validation, error categories, retryability, timeouts, cancellation, and partial failure.14- Use idempotency for retryable mutations and define concurrency/conflict semantics.15- Design pagination, filtering, ordering, field selection, limits, and consistency explicitly.16- Bound payloads and document rate limits, quotas, and abuse controls.17- Use stable names and additive evolution; document deprecation, versioning, and migration for breaking changes.1819Provide representative success and failure examples plus contract tests. For event APIs, also define delivery guarantees, ordering, duplication, schema evolution, replay, and dead-letter handling.
egeetas