API Design

Design clear, consistent, and developer-friendly REST APIs.

When NOT to Use

Consuming external APIs — Use api-integration for building clients to call third-party services (Stripe, Twilio, etc.)
Writing tests for APIs — Use testing-strategy for contract tests, integration tests, mocking strategies
Reviewing existing API security — Use security-audit for vulnerability scanning of live endpoints
Designing auth mechanisms that are the whole task — Use security-audit if reviewing, this skill if designing from scratch

Resource-oriented — Design around nouns (resources), not verbs (actions)
Predictable patterns — Consistent URL structure, response format, and behavior
Clear contracts — Explicit schemas, documented errors, versioned endpoints
Developer experience — Meaningful errors, helpful examples, logical defaults

Method	Purpose	Idempotent	Body
GET	Read	Yes	No
POST	Create	No	Yes
PUT	Replace	Yes	Yes
PATCH	Partial update	Yes*	Yes
DELETE	Remove	Yes	No

Reference	Description
endpoints.md	URL design, HTTP methods, resource modeling
requests-responses.md	Request/response formats, headers, content types
status-codes.md	HTTP status codes, error handling patterns
pagination-filtering.md	Pagination, filtering, sorting, searching
versioning.md	API versioning strategies
openapi.md	OpenAPI specification, documentation
security.md	Authentication, authorization, rate limiting
tdd-patterns.md	Test-first patterns for REST endpoints, supertest templates
review-checklist.md	API design review checklist (validation, auth, performance, docs)