api

name	api
description	Design and scaffold APIs with contracts, validation, error handling, tests, documentation, and consumer impact awareness.

API

Use this for REST, RPC, GraphQL, route handlers, service layers, and request/response design.

Workflow

1. Clarify the contract: inputs, outputs, auth, errors, idempotency, pagination, filtering.
2. Define request and response types.
3. Add validation at the boundary.
4. Keep handler, service, and persistence concerns separated.
5. Implement typed error handling and consistent status codes.
6. Add tests for success, validation failure, auth failure, and service errors.
7. Update docs and client usage.

Architecture rules

• Thin controllers, rich services.
• Validate early.
• Keep domain logic out of transport glue.
• Design backward-compatible changes where possible.

Output format

• Proposed contract
• Suggested file layout
• Implementation notes
• Tests required
• Breaking change risk