/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