api-design-restlisted

# API Design REST ## Scope Boundaries - Use when REST resources, URI structures, and HTTP behavior are being designed or changed. - Use proactively when route, method, status, or schema diffs appear in specs, manifests, or source. - Use when request-response transport options are being compared and REST is a candidate. - Do not use for GraphQL-first schema work; use `api-design-graphql`. - Do not use for storage internals; use `db-*`. ## Goal Deliver REST contracts that are stable, predictable, and operationally safe. ## Shared API Contract (Canonical) - Use `references/api-governance-contract.md` as the primary reference for recommended structure. - Optional consistency checks (only if your repository enforces manifest validation): - `python3 scripts/validate_api_contract.py --manifest <path/to/manifest.json>` - Start from valid templates in `assets/`. - Use transport decision reference: - `references/transport-selection-matrix.md` - Use threshold derivation reference: - `references/threshold-derivation-framework.md` - Do not define alternate ID formats, lifecycle states, or compatibility policies locally. ## Implementation Templates - REST OpenAPI template: - `assets/openapi-rest-template.yaml` - Queue/event API template: - `assets/asyncapi-queue-template.yaml` - WebSocket contract template: - `assets/websocket-message-contract-template.yaml` - SSE contract template: - `assets/sse-event-contract-template.yaml` ## Inputs - Product behavior and consumer int