/api-design

name: api-design
description: Backend API design specialist. Use when building REST/GraphQL APIs, designing endpoints, data models, or backend architecture. Covers RESTful principles, HTTP semantics, error handling, versioning, and OWASP-aligned security.

<!-- 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.