---
name: api-design
description: >-
  Designs clear, consistent, evolvable REST and GraphQL APIs with proper resource
  modeling, error handling, and pagination. Use when designing new endpoints, reviewing
  API architecture, or user asks to "design an API for X".
  NOT for implementing API code, writing API docs, or debugging API errors.
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---

## Identity & Scope

**Executor:** either
**Model tier:** sonnet
**Scope:** API endpoint definitions, route files, schema files, OpenAPI specs
**Off-limits:** Implementing endpoint code, modifying databases, deploying APIs
**Hard rules:** No credentials in output. No deleting files. No spending money. Report via structured output.

## Essential Principles

1. **Design for the consumer** — Model resources around caller needs, not database structure. Guards against: leaking implementation into the public contract.
2. **Consistent shapes everywhere** — Every endpoint returns {data, meta, errors}. Guards against: per-endpoint parsing logic.
3. **Version from day one** — Include /api/v1/ even if you think you won't need it. Guards against: breaking changes with no migration path.
4. **Paginate all collections** — Every list endpoint supports pagination from the start. Guards against: endpoints that crash at scale.

## When to Use
- Designing endpoints for a new service or feature
- Reviewing an existing API for consistency
- User asks to "design an API for X" or "review this API"
- Planning API versioning or migration strategy
- Standardizing error response formats

## When NOT to Use
- Implementing the API in code — use language/framework skill
- Writing API documentation — use documentation-writing skill
- Debugging API errors — use bug-debugging skill
- Database schema design — use database-schema skill

## Rationalizations to Reject

| Shortcut | Why it's wrong |
|----------|----------------|
| "Add pagination later" | Retrofitting pagination breaks existing consumers |
| "Versioning is overkill" | Small APIs grow; unversioned changes break clients silently |
| "Return database row directly" | Leaks internal schema, couples consumers to DB |
| "One endpoint with action query params" | Violates REST resource modeling, unpredictable API |

## Workflow

### Phase 1: Requirements
**Entry:** Feature description or use cases available
**Actions:**
1. Identify resources (nouns) the API will expose
2. Map relationships between resources
3. List operations consumers need per resource
4. Identify auth/authz requirements
**Exit:** Resource list with relationships and operations

### Phase 2: Design Endpoints
**Entry:** Requirements complete
**Actions:**
1. Define paths using plural nouns: /api/v1/users, /api/v1/orders
2. Map HTTP methods: GET, POST, PUT, PATCH, DELETE
3. Define nested routes for relationships: /users/{id}/orders
4. Specify query params for filtering, sorting, pagination
5. Define response envelope: {data, meta, errors}
6. Define error format with HTTP status codes and actionable messages
**Exit:** Complete endpoint spec with paths, methods, params, responses

### Phase 3: Validate Design
**Entry:** Spec complete
**Actions:**
1. Verify every list endpoint has pagination
2. Verify consistent response shapes across all endpoints
3. Verify correct HTTP status codes (200, 201, 204, 400, 401, 403, 404, 422, 500)
4. Check idempotency: PUT and DELETE safe to retry
5. Check rate limiting is specified
**Exit:** Design validated against checklist

### Phase 4: Verify
**Entry:** Validation complete
**Actions:**
1. Confirm all resources have CRUD operations where appropriate
2. Confirm no internal IDs or implementation details leaked
3. Confirm output matches required JSON format
**Exit:** All checks pass — report results

## Output Format

```json
{
  "skill": "api-design",
  "status": "completed",
  "worker": "worker-id",
  "summary": "Designed 12 endpoints across 3 resources (users, orders, products) with pagination and auth",
  "findings": [
    {"item": "GET /api/v1/users — cursor pagination", "severity": "info", "detail": "Params: ?cursor=abc&limit=20&status=active. Response: {data:[User], meta:{next_cursor,total}, errors:[]}"},
    {"item": "POST /api/v1/orders — not idempotent", "severity": "high", "detail": "No idempotency key. Add Idempotency-Key header to prevent duplicate orders on retry"}
  ],
  "errors": [],
  "elapsed_seconds": 39.8
}
```

**Bad example:** `{"summary": "Designed the API", "findings": [{"item": "endpoints created"}]}` — no details, no resource names, impossible to implement from.

## Escalation Triggers

STOP and report to boss when:
- API needs breaking changes to an already-published version
- Auth requirements unclear or require third-party decisions
- API handles financial transactions or PII with compliance requirements
- Relationships too complex for standard REST patterns
- Real-time features (WebSockets, SSE) needed beyond REST

## Success Criteria

- [ ] All resources have RESTful endpoints with proper naming
- [ ] Every list endpoint has pagination
- [ ] Consistent response shapes across all endpoints
- [ ] Error responses include status codes and actionable messages
- [ ] API versioned (/api/v1/)
- [ ] Auth specified per endpoint
- [ ] Output matches JSON format above
- [ ] No unresolved escalation triggers
