api-designlisted

# api-design ## Purpose Two modes: - **Design mode** (`/api-design`): Design a new API surface from requirements — resource modeling, endpoint naming, request/response schemas, versioning, auth, error contracts, pagination. - **Review mode** (`/api-design --review`): Audit an existing API for consistency, best practices violations, and breaking change risks. --- ## DESIGN MODE Instructions ### Step 1 — Gather inputs Ask the user: - What does this API do? (domain / resource description) - Who are the consumers? (web frontend, mobile app, third-party, internal service) - What protocol? REST, GraphQL, gRPC, or WebSocket (or combination) - What auth mechanism? (JWT Bearer, API Key, OAuth2, mTLS) - Any existing APIs this must be consistent with? Read any existing API files: `openapi.yml`, `schema.graphql`, `*.proto`, Swagger docs. --- ### Step 2 — Resource Modeling (REST) Identify the core resources from the domain description. For each resource: - Name it as a plural noun: `/users`, `/orders`, `/products` - Define its fields (name, type, required/optional, description) - Define its relationships (belongs_to, has_many) - Map CRUD to HTTP methods: | Operation | Method | Path | Notes | |-----------|--------|------|-------| | List | GET | /resources | Supports filtering, sorting, pagination | | Get one | GET | /resources/:id | 404 if not found | | Create | POST | /resources | 201 + Location header on success | | Update (full) | PUT | /resources/:id | Idempotent | | Update