Design REST API Action

Design a complete RESTful API architecture with resource endpoints, authentication, validation, versioning, OpenAPI documentation, and performance optimization following industry best practices.

When to Use This Command

Run this command when...

• You are designing a new REST API and need a complete resource structure with proper HTTP methods and status codes
• You want OpenAPI/Swagger specification generated alongside your API design for interactive documentation
• You need to plan authentication (JWT, OAuth, API keys), authorization (RBAC), and rate limiting for your API
• You are implementing versioning, pagination, filtering, and error handling patterns from scratch
• You want to design webhook integrations, file upload endpoints, or batch operations within a RESTful framework

Quick Start

Copy
# .claude/commands/design-rest-api-action.yaml
name: Design REST API Action
description: Design comprehensive RESTful API with OpenAPI specs
inputs:
  - name: domain
    description: "API domain or resource description"
  - name: version
    description: "API version strategy"
    default: "url"

Copy
# Design an e-commerce API
claude "design-rest-api --domain 'e-commerce with products, orders, users'"

# Design with OpenAPI spec output
claude "design-rest-api --domain 'task management' --version url --output openapi"

Output:
  [detect] Framework: Express.js
  [design] Resources identified: products, orders, users, carts
  [endpoints] Generated 24 endpoints across 4 resources
  [auth] JWT authentication with refresh tokens
  [docs] OpenAPI 3.0 spec generated (swagger.yaml)
  [validate] All endpoints follow REST conventions
  Done. API design with 24 endpoints ready.

Core Concepts

Concept	Description
Resource Design	Identifies resources from domain description and generates CRUD endpoints with proper HTTP verbs
Status Codes	Maps appropriate HTTP status codes: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 422 Unprocessable
Versioning	Supports URL-based (/v1/), header-based, or content-type versioning strategies
OpenAPI Spec	Generates Swagger/OpenAPI 3.0 definitions with schemas, examples, and interactive documentation
Error Handling	Standardized error response format with error codes, messages, and field-level validation details

API Resource Structure:
  /api/v1
  ├── /products
  │   ├── GET    / (list, paginated)
  │   ├── POST   / (create)
  │   ├── GET    /:id (read)
  │   ├── PUT    /:id (replace)
  │   ├── PATCH  /:id (partial update)
  │   └── DELETE /:id (remove)
  ├── /orders
  │   ├── GET    /
  │   ├── POST   /
  │   └── GET    /:id
  └── /users
      ├── GET    /me (current user)
      └── PATCH  /me (update profile)

Configuration

Parameter	Type	Default	Description
domain	string	required	API domain description with resource names and relationships
version	string	"url"	Versioning strategy: url (/v1/), header, or content-type
auth	string	"jwt"	Authentication method: jwt, oauth, api-key, or none
output	string	"design"	Output format: design (markdown), openapi (swagger.yaml), or both
pagination	string	"cursor"	Pagination style: cursor-based, offset-based, or keyset

Best Practices

1. Use nouns for resources, not verbs -- Endpoints should be /users and /orders, not /getUsers or /createOrder. HTTP methods already convey the action.
2. Implement cursor-based pagination -- Offset pagination breaks when data changes between requests. Cursor-based pagination provides stable results and better performance on large datasets.
3. Version from day one -- Adding versioning after clients depend on your API creates breaking changes. Start with /v1/ even if you do not plan version 2 yet.
4. Return consistent error formats -- Every error response should use the same JSON structure with error.code, error.message, and error.details so clients can parse errors uniformly.
5. Generate and publish OpenAPI specs -- The generated swagger.yaml serves as both documentation and a contract. Use it to auto-generate client SDKs and validate request/response schemas.

Common Issues

1. Nested resources go too deep -- Avoid nesting beyond two levels (e.g., /users/:id/orders is fine, /users/:id/orders/:id/items/:id/reviews is not). Use top-level resources with query filters instead.
2. Inconsistent status codes -- The design uses standard codes but custom endpoints may drift. Review all endpoints to ensure 201 for creation, 204 for deletion, and 422 for validation errors.
3. Missing rate limiting in design -- The API design does not implement rate limiting by default. Add it as a follow-up step using the setup-rate-fast command.