API Design

API Design

Overview

Structured API endpoint design through guided discovery. Produces consistent, well-documented API designs with OpenAPI/Swagger specifications. Covers resource modeling, authentication, pagination, error handling, and versioning — ensuring consumer-centric design before any implementation begins.

Announce at start: "I'm using the api-design skill to design the API."

Phase 1: Discovery

Ask these questions ONE AT A TIME:

Resource Questions

Consumer Questions

Constraint Questions

API Paradigm Decision Table

STOP after discovery — present a summary of resources, operations, and constraints. Get confirmation before designing endpoints.

Phase 2: Design Endpoints

For each endpoint, define:

### [METHOD] /api/v1/[resource]

**Purpose:** [what this endpoint does]

**Request:**
- Headers: `Authorization: Bearer <token>`
- Query params: `?page=1&limit=20&sort=created_at:desc`
- Body:
  ```json
  {
    "field": "type — description"
  }

Response (200):

{
  "data": [...],
  "meta": { "total": 100, "page": 1, "limit": 20 }
}

Error Responses:

Authorization: [who can access this]

### HTTP Method Decision Table

| Operation | Method | Status (success) | Idempotent |
|-----------|--------|-----------------|------------|
| List resources | GET | 200 | Yes |
| Get single resource | GET | 200 | Yes |
| Create resource | POST | 201 | No |
| Full replace | PUT | 200 | Yes |
| Partial update | PATCH | 200 | No |
| Delete resource | DELETE | 204 | Yes |
| Bulk create | POST | 201 | No |
| Search (complex) | POST | 200 | Yes (safe) |

### Pagination Decision Table

| Approach | When to Use | Pros | Cons |
|----------|------------|------|------|
| **Cursor** | Real-time feeds, large datasets | Consistent, no skipping | Cannot jump to page N |
| **Offset** | Small datasets, admin panels | Simple, jumpable | Skips/duplicates on insert |
| **Keyset** | Time-series, logs | Efficient on large tables | Requires sortable key |

### Error Response Format

All endpoints must use a consistent error shape:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

Status Code Reference

STOP after endpoint design — present each endpoint for review and approval.

Phase 3: Generate OpenAPI Spec

openapi: 3.1.0
info:
  title: [API Name]
  version: 1.0.0
  description: [API description]

servers:
  - url: http://localhost:3000/api/v1
    description: Development
  - url: https://api.example.com/v1
    description: Production

paths:
  /resource:
    get:
      summary: List resources
      parameters: [...]
      responses: [...]
    post:
      summary: Create resource
      requestBody: [...]
      responses: [...]

components:
  schemas: [...]
  securitySchemes: [...]

STOP after spec generation — validate the YAML and present for final approval.

Phase 4: Save and Transition

After explicit approval:

1. Save OpenAPI spec to docs/api/YYYY-MM-DD-<api-name>.yaml
2. Commit with message: docs(api): add OpenAPI spec for <api-name>
3. Determine next step based on user intent

Transition Decision Table

Design Principles

Anti-Patterns / Common Mistakes

Anti-Rationalization Guards

• Do NOT skip the discovery phase — understand consumers and constraints first
• Do NOT design endpoints without defining error responses
• Do NOT skip pagination for any list endpoint
• Do NOT use inconsistent naming across endpoints
• Do NOT generate the OpenAPI spec without user approval of endpoint designs
• Do NOT mix API paradigms (REST + GraphQL) without explicit justification

Integration Points

Verification Gate

Before claiming the API design is complete:

1. VERIFY all endpoints have request/response schemas
2. VERIFY all error responses are documented with consistent format
3. VERIFY authentication is specified for each endpoint
4. VERIFY pagination is defined for all list endpoints
5. VERIFY the OpenAPI spec is valid YAML
6. VERIFY user has approved each endpoint individually

Skill Type

Flexible — Adapt API paradigm, pagination style, and auth model to project needs while preserving the discovery-first approach, consistent error handling, and consumer-centric design principles.