api-designer

API Designer

Design API contracts before implementation. Define endpoints, schemas, error codes, and conventions. The contract is the source of truth — implementation follows it.

Rules

1. Contract first — design the API before writing handler code
2. Consistency — follow existing API patterns in the project (scan src/ first)
3. Check specs — read versioning spec (API strategy) and security spec (auth, rate limiting)
4. Resource-oriented — REST: nouns, not verbs. GraphQL: types and fields, not endpoints
5. Error handling is part of the design — define error codes and response format upfront
6. Pagination for lists — never return unbounded collections
7. ADR for new patterns — if introducing a new API convention, create an ADR

Workflow

Phase 1: Context

1. Read the PRD requirements for the API
2. Scan existing endpoints: grep -r "router\|app\.\(get\|post\|put\|delete\|patch\)" src/ (or [SPEC] equivalent)
3. Read docs/specs/versioning/ for API versioning strategy
4. Read docs/specs/security/ for auth and rate limiting patterns
5. Read docs/specs/api/ for API conventions (if exists)
6. Check memory for past API design decisions

Phase 2: Design

For each endpoint, define:

[METHOD] /api/v{N}/{resource}

Description: What this endpoint does (one line)
Auth: [required | public | specific role]
Rate limit: [requests/window]

Request:
  Headers: [required headers]
  Params: [path and query params with types]
  Body: [schema with required/optional fields]

Response 200:
  {schema}

Response 4xx/5xx:
  {
    "error": {
      "code": "SPECIFIC_ERROR_CODE",
      "message": "Human-readable description"
    }
  }

Phase 3: Conventions checklist

• Naming: plural nouns for resources (/users, not /user)
• HTTP methods: GET (read), POST (create), PUT (full update), PATCH (partial), DELETE (remove)
• Status codes: 200 (ok), 201 (created), 204 (no content), 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 409 (conflict), 422 (validation), 429 (rate limited), 500 (server error)
• Pagination: ?page=1&limit=20 or cursor-based, with total, hasMore in response
• Filtering: ?status=active&sort=created_at&order=desc
• Versioning: follows strategy from versioning spec (URL prefix, header, or query)
• Error format: consistent across all endpoints
• Dates: ISO 8601 (2026-04-01T12:00:00Z)
• IDs: consistent format (UUID, nanoid, auto-increment — pick one)