API Design

<!--

Source: wshobson/agents (backend-development plugin)

File: https://github.com/wshobson/agents/tree/main/plugins/backend-development/skills/api-design-principles

Used by: builder agent (backend)

-->

API Design Principles

When to trigger

• Designing a new API endpoint
• Adding routes to existing API
• Database schema work that affects API contract
• Keywords: "endpoint", "API", "route", "backend", "server", "REST", "GraphQL"

Core RESTful principles

Resource-oriented URLs

• Nouns, not verbs: /users/123, not /getUser?id=123
• Pluralize resources: /orders, not /order
• Nest only when expressing parent/child: /users/:id/orders
• Max 2 levels deep — beyond that, use query params

HTTP methods (correct semantics)

| Method | Use for | Idempotent | Safe |

|--------|---------|------------|------|

| GET | Read | Yes | Yes |

| POST | Create | No | No |

| PUT | Replace (full update) | Yes | No |

| PATCH | Partial update | No* | No |

| DELETE | Remove | Yes | No |

\* PATCH can be idempotent depending on semantics.

Status codes (correct use)

• 200 OK — successful GET/PUT/PATCH with body
• 201 Created — successful POST creating resource
• 204 No Content — successful DELETE or action with no body
• 400 Bad Request — validation failure
• 401 Unauthorized — missing/invalid auth
• 403 Forbidden — authenticated but not authorized
• 404 Not Found — resource doesn't exist
• 409 Conflict — version mismatch, duplicate resource
• 422 Unprocessable Entity — semantic validation failure
• 429 Too Many Requests — rate limited
• 500 Internal Server Error — unhandled server fault

Response envelope

Consistent shape for all responses:

{
  success: boolean
  data: T | null
  error: string | null
  metadata?: { total, page, limit }
}

Endpoint design patterns

Pagination

• Cursor-based for large/changing sets: ?cursor=abc&limit=20
• Offset-based for small stable sets: ?page=1&limit=20
• Always cap limit server-side (max 100)

Filtering

• Query params: ?status=active&created_after=2024-01-01
• Sort: ?sort=-created_at (minus prefix = descending)

Versioning

• URL path: /v1/users, /v2/users (easiest to deprecate)
• Never introduce breaking changes to existing version

Security (mandatory)

• Authentication — every non-public endpoint checks auth first
• Authorization — row-level checks, not just auth-exists
• Input validation — Zod schema on every request body + query
• Rate limiting — public routes + AI/LLM routes especially
• CORS — whitelist, not *
• Output filtering — never leak internal IDs or PII in error messages
• Webhook signatures — verify signature before trusting payload

Error handling

• Never expose stack traces to the client
• Log server-side with request ID
• Return structured error: { code: "INVALID_INPUT", message: "...", field: "email" }
• HTTP status code must match error type

Output format

## API Design Summary

### Endpoint
`<METHOD> /path/to/resource`

### Purpose
<what it does, who uses it>

### Request
- **Auth:** <required | optional>
- **Body schema:** Zod
- **Query params:** ...

### Response
- **200:** <shape>
- **Error cases:** 400, 401, 403, 404, 422, 429, 500

### Security checks
- [ ] Auth verified
- [ ] Authorization verified (row-level)
- [ ] Input validated (Zod)
- [ ] Rate limit applied
- [ ] PII not leaked in errors

### Dependencies
- Database tables: <list>
- External services: <list>

Rules

• RESTful first. Only use GraphQL / RPC if there's a concrete reason.
• No breaking changes to existing API versions. Ever.
• Every endpoint validates input — no "we'll add validation later".
• Every endpoint has a test (unit for business logic, integration for HTTP layer).
• Document before coding. OpenAPI spec or at least a Markdown contract.
• Rate limit on day 1 — retrofitting is painful.