name: designing-apis description: Design clean, consistent APIs. Use when creating new endpoints, defining contracts, or improving API ergonomics. Covers REST, versioning, and error handling. allowed-tools: Read, Write, Glob, Grep

Designing APIs

Workflows

• Resources: Identify resources and relationships
• Endpoints: Define URL structure and methods
• Request/Response: Define payloads and schemas
• Errors: Define error responses
• Document: Create OpenAPI spec

REST Principles

Resource Naming

• Use nouns, not verbs: /users not /getUsers
• Use plural: /users not /user
• Use kebab-case: /user-profiles not /userProfiles
• Nest for relationships: /users/{id}/orders

HTTP Methods

Status Codes

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Versioning

URL Versioning (Recommended)

GET /api/v1/users
GET /api/v2/users

Header Versioning

GET /api/users
Accept: application/vnd.api+json;version=1

Pagination

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}

OpenAPI Example

openapi: 3.0.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'