api-designlisted

# REST API Design Patterns Conventions for designing consistent, developer-friendly REST APIs in TypeScript/Node. ## When to Activate - Designing new API endpoints - Reviewing existing API contracts - Adding pagination, filtering, or sorting - Planning an API versioning strategy - Building public or partner-facing APIs > Auth depth (JWT/sessions/OAuth/RBAC) and rate-limiting implementation live in the > dedicated auth and rate-limiting skills — this skill only covers how they appear in > the API contract (status codes, headers). ## Resource Design ### URL Structure ``` # Resources are nouns, plural, lowercase, kebab-case GET /api/v1/users GET /api/v1/users/:id POST /api/v1/users PUT /api/v1/users/:id PATCH /api/v1/users/:id DELETE /api/v1/users/:id # Sub-resources for relationships GET /api/v1/users/:id/orders # Actions that don't map to CRUD (use verbs sparingly) POST /api/v1/orders/:id/cancel POST /api/v1/auth/login ``` ### Naming Rules ``` # GOOD /api/v1/team-members # kebab-case for multi-word resources /api/v1/orders?status=active # query params for filtering /api/v1/users/123/orders # nested resources for ownership # BAD /api/v1/getUsers # verb in URL /api/v1/user # singular (use plural) /api/v1/team_members # snake_case in URLs ``` ## HTTP Methods and Status Codes | Method | Idempotent | Safe | Use For | |--------|-----------|------|---------| | GET | Yes | Yes | Retrieve resources |