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)