Design api

# /api-architect:design-api

Design a RESTful or GraphQL API based on the project's domain model and requirements.

## Process

1. Analyze the existing codebase to understand the domain:
   - Read database models, schemas, or type definitions to identify entities
   - Check existing routes or resolvers to understand current API surface
   - Look for DTOs, serializers, or validation schemas
   - Identify relationships between entities (one-to-many, many-to-many)

2. Design the resource hierarchy following REST conventions:
   - Map each core entity to a resource with a plural noun URL (`/users`, `/orders`, `/products`)
   - Nest sub-resources only one level deep (`/users/{id}/orders`, not `/users/{id}/orders/{id}/items`)
   - Use query parameters for filtering, sorting, and pagination on collection endpoints
   - Define standard operations for each resource:
     - `GET /resources` - List with pagination (cursor-based preferred over offset)
     - `GET /resources/{id}` - Retrieve single resource
     - `POST /resources` - Create new resource
     - `PUT /resources/{id}` - Full update (replace)
     - `PATCH /resources/{id}` - Partial update
     - `DELETE /resources/{id}` - Remove resource

3. Define request and response shapes:
   - Use consistent envelope format: `{ "data": ..., "meta": { "total", "cursor" } }`
   - Include only necessary fields in list responses (summary representation)
   - Return full representation on single-resource endpoints
   - Define error response format: `{ "error": { "code": "...", "message": "...", "details": [...] } }`
   - Use ISO 8601 for dates, UUIDs for identifiers, lowercase snake_case for field names

4. Design authentication and authorization:
   - Recommend Bearer token (JWT or opaque) via Authorization header
   - Define permission model: which roles can access which endpoints
   - Identify public vs authenticated vs admin-only endpoints
   - Include rate limiting headers in response design (X-RateLimit-Limit, X-RateLimit-Remaining)

5. Plan for versioning:
   - Recommend URL prefix versioning (`/v1/resources`) for simplicity
   - Document the deprecation policy for old versions
   - Design backward-compatible extension patterns (additive fields, optional parameters)

6. Design cross-cutting concerns:
   - Pagination: cursor-based with `?cursor=` and `?limit=` parameters
   - Filtering: field-based query params (`?status=active&created_after=2024-01-01`)
   - Sorting: `?sort=created_at:desc,name:asc`
   - Field selection: `?fields=id,name,email` for bandwidth optimization
   - Bulk operations: `POST /resources/batch` for creating multiple items

## Output

Present the API design as a structured table of endpoints with:
- HTTP method and path
- Description
- Request body (if applicable)
- Response shape
- Authentication requirement
- Example curl command for each endpoint

## Rules

- Follow the principle of least surprise: APIs should behave as developers expect
- Use standard HTTP status codes correctly (201 for creation, 204 for deletion, 409 for conflicts)
- Design idempotent operations where possible (PUT and DELETE should be safe to retry)
- Never expose internal IDs, database column names, or implementation details
- Consider forward compatibility: design fields that can be extended without breaking clients
- Ask the user for clarification on business rules before making assumptions