version: "1.0.0" 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)

\* 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.