API Design First

Design RESTful APIs using design-first principles with comprehensive OpenAPI 3.0 specifications.

When to Use

• User asks to design an API or create an API spec
• Planning endpoints, modeling request/response schemas
• Discussing API versioning or OpenAPI/Swagger documentation
• Even if they just say "design the API" or "create the OpenAPI spec"

Design Principles

1. API-First Mindset

• Design the API contract before implementation
• Use OpenAPI 3.0 as the source of truth
• Generate code from specifications, not vice versa

2. RESTful Design

• Use nouns for resources (not verbs)
• Leverage HTTP methods semantically
• Implement proper status codes
• Support filtering, pagination, and sorting

3. Consistency

• Follow naming conventions throughout
• Use consistent request/response formats
• Maintain backward compatibility with versioning

Resource Naming

GET    /users              # List users
GET    /users/{id}         # Get specific user
POST   /users              # Create user
PUT    /users/{id}         # Update user (full)
PATCH  /users/{id}         # Partial update
DELETE /users/{id}         # Delete user
GET    /users/{id}/orders  # Sub-resource collection

HTTP Status Codes

Request/Response Patterns

Pagination

{
  "data": [...],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  },
  "links": {
    "self": "/users?page=1",
    "next": "/users?page=2",
    "last": "/users?page=8"
  }
}

Error Response

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

OpenAPI Structure

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Success

Versioning Strategies

1. URL Path: /v1/users, /v2/users
2. Header: Accept: application/vnd.api+json;version=2
3. Query Param: /users?api-version=2

See Also

• cloudflare-worker-api — Cloudflare Worker API routes
• secure-invite-and-access — Auth endpoints and permissions

Rationalizations

Red Flags

• Designing endpoints without an OpenAPI specification first
• Using verbs in resource URLs instead of nouns with HTTP methods
• Ignoring versioning strategy until breaking changes force a rewrite

References

• references/rest-guidelines.md - Comprehensive REST design guidelines
• references/openapi-examples.md - Complete OpenAPI 3.0 specification examples
• references/naming-conventions.md - Resource and field naming standards

Voice & Context

• Default: professional + blog
• Reference: voice-profiles skill for definitions and auto-detection.