API Design
Design clear, consistent, and developer-friendly REST APIs.
When NOT to Use
- Consuming external APIs — Use
api-integrationfor building clients to call third-party services (Stripe, Twilio, etc.) - Writing tests for APIs — Use
testing-strategyfor contract tests, integration tests, mocking strategies - Reviewing existing API security — Use
security-auditfor vulnerability scanning of live endpoints - Designing auth mechanisms that are the whole task — Use
security-auditif reviewing, this skill if designing from scratch
Core Principles
- 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
Quick Start Checklist
- Identify resources and their relationships
- Define CRUD operations + custom actions with correct HTTP methods
- Design request/response schemas with consistent envelope
- Plan error format with status codes, error codes, and field-level details
- Write OpenAPI specification with examples
- Review for consistency, security, and usability
Design Quick Reference
| 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 |
References
| 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) |