1---
2name: api-design
3description: Use when designing new REST APIs, reviewing API designs, establishing API standards, designing request/response formats, pagination, versioning, authentication flows, or creating OpenAPI specifications.
4---
5
6# API Design
7
8Design clear, consistent, and developer-friendly REST APIs.
9
10## When NOT to Use
11
12- **Consuming external APIs** — Use `api-integration` for building clients to call third-party services (Stripe, Twilio, etc.)
13- **Writing tests for APIs** — Use `testing-strategy` for contract tests, integration tests, mocking strategies
14- **Reviewing existing API security** — Use `security-audit` for vulnerability scanning of live endpoints
15- **Designing auth mechanisms** that are the whole task — Use `security-audit` if reviewing, this skill if designing from scratch
16
17## Core Principles
18
19- **Resource-oriented** — Design around nouns (resources), not verbs (actions)
20- **Predictable patterns** — Consistent URL structure, response format, and behavior
21- **Clear contracts** — Explicit schemas, documented errors, versioned endpoints
22- **Developer experience** — Meaningful errors, helpful examples, logical defaults
23
24## Quick Start Checklist
25
261. Identify resources and their relationships
272. Define CRUD operations + custom actions with correct HTTP methods
283. Design request/response schemas with consistent envelope
294. Plan error format with status codes, error codes, and field-level details
305. Write OpenAPI specification with examples
316. Review for consistency, security, and usability
32
33## Design Quick Reference
34
35| Method | Purpose | Idempotent | Body |
36|--------|---------|------------|------|
37| GET | Read | Yes | No |
38| POST | Create | No | Yes |
39| PUT | Replace | Yes | Yes |
40| PATCH | Partial update | Yes* | Yes |
41| DELETE | Remove | Yes | No |
42
43## References
44
45| Reference | Description |
46|-----------|-------------|
47| [endpoints.md](references/endpoints.md) | URL design, HTTP methods, resource modeling |
48| [requests-responses.md](references/requests-responses.md) | Request/response formats, headers, content types |
49| [status-codes.md](references/status-codes.md) | HTTP status codes, error handling patterns |
50| [pagination-filtering.md](references/pagination-filtering.md) | Pagination, filtering, sorting, searching |
51| [versioning.md](references/versioning.md) | API versioning strategies |
52| [openapi.md](references/openapi.md) | OpenAPI specification, documentation |
53| [security.md](references/security.md) | Authentication, authorization, rate limiting |
54| [tdd-patterns.md](references/tdd-patterns.md) | Test-first patterns for REST endpoints, supertest templates |
55| [review-checklist.md](references/review-checklist.md) | API design review checklist (validation, auth, performance, docs) |
srstomp