API Design Review
Review the contract from the perspective of its callers and operators.
- Define resource/operation semantics, identifiers, input schema, output schema, and expected state transitions.
- Make validation and error behavior consistent, actionable, and safe to expose.
- Check authentication, authorization, rate limits, idempotency, pagination, filtering, and concurrency where relevant.
- Consider backwards compatibility, versioning, deprecation, retries, timeouts, and partial failures.
- Avoid leaking internal implementation details or sensitive data through responses and logs.
- Provide examples for success, validation failure, authorization failure, and important boundary cases.
- Verify the contract against actual implementation and tests.
Prefer stable, boring contracts over clever ones. Do not add fields or endpoints for hypothetical consumers. Distinguish breaking changes from additive changes and identify the migration required for each affected client.