Skip to content
/api-designStable

Designs REST or GraphQL APIs from requirements with typed schemas, validation rules, error contracts, and example requests.

APIArchitecture· 3 min read

Quick import: Download the .md file and save it to .claude/commands/ (Claude Code), .cursorrules (Cursor), or paste as a system prompt in ChatGPT, Gemini, or any LLM API.

#What it does

The /api-design skill translates product requirements into a complete API specification. It defines endpoints, request/response schemas, validation rules, error contracts, authentication requirements, and pagination strategies. The output is a ready-to-implement API design that follows REST conventions (or GraphQL schema) with TypeScript types you can drop directly into your codebase.

#How to use

bash
/api-design User management with registration, login, profile updates, and role-based access
bash
/api-design --style graphql E-commerce product catalog with search, filtering, and inventory

#Workflow

  1. Requirements -- Parse the feature description into discrete API operations (CRUD, search, actions, webhooks)
  2. Resource Modeling -- Define the core resources, their relationships, and which fields are public vs. internal
  3. Endpoint Design -- Map operations to HTTP methods and URL patterns following REST conventions
  4. Schema Definition -- Create TypeScript types for request bodies, response payloads, query parameters, and error responses
  5. Validation Rules -- Define constraints for every input field (required, min/max, regex, enum values)
  6. Error Contract -- Design consistent error responses with machine-readable codes and human-readable messages
  7. Documentation -- Generate OpenAPI-compatible documentation with example requests and responses

#Example

bash
> /api-design Task management with projects, tasks, assignments, and due dates
 
## Resources
- Project { id, name, description, createdAt }
- Task { id, projectId, title, status, assigneeId, dueDate, priority }
 
## Endpoints
 
### Projects
POST   /api/v1/projects              — Create project
GET    /api/v1/projects               — List projects (paginated)
GET    /api/v1/projects/:id           — Get project by ID
PATCH  /api/v1/projects/:id           — Update project
DELETE /api/v1/projects/:id           — Soft delete project
 
### Tasks
POST   /api/v1/projects/:id/tasks    — Create task in project
GET    /api/v1/projects/:id/tasks    — List tasks (filterable, paginated)
PATCH  /api/v1/tasks/:id             — Update task
POST   /api/v1/tasks/:id/assign      — Assign task to user
 
## Request Schema: Create Task
{
  title: string          // required, 1-200 chars
  status: "todo" | "in_progress" | "done"  // default: "todo"
  assigneeId?: string    // optional, must be valid user ID
  dueDate?: string       // optional, ISO 8601 format, must be future
  priority: 1 | 2 | 3   // required, 1=high 3=low
}
 
## Error Contract
{
  error: {
    code: "VALIDATION_ERROR" | "NOT_FOUND" | "FORBIDDEN",
    message: "Human-readable description",
    details?: [{ field: "title", issue: "Required field missing" }]
  }
}

#Design principles

  • Plural resource names (/projects, not /project)
  • Versioned URLs (/api/v1/) for backward compatibility
  • PATCH for partial updates, PUT only for full replacement
  • Consistent pagination with ?page=1&limit=25 and total count in response headers
  • Idempotency keys for POST operations that create resources
Orel Ohayon·
View all skills