api-conventionslisted

# API Design Conventions Skill Enforce consistent API design across all projects. ## When This Activates - Writing API routes or HTTP handlers - Creating response objects - Designing REST endpoints - Adding pagination or filtering - Implementing rate limiting ## RESTful Resource Naming ``` GET /api/users → List users GET /api/users/:id → Get single user POST /api/users → Create user PATCH /api/users/:id → Update user (partial) PUT /api/users/:id → Replace user (full) DELETE /api/users/:id → Delete user # Nested resources GET /api/users/:id/posts → List user's posts # Actions (when CRUD doesn't fit) POST /api/users/:id/verify → Trigger verification POST /api/orders/:id/cancel → Cancel order ``` **Rules:** - Plural nouns for resources (`/users` not `/user`) - Kebab-case for multi-word (`/order-items` not `/orderItems`) - No verbs in URLs (use HTTP methods instead) - Max 2 levels of nesting ## Response Shape All responses follow this shape: ```typescript // Success { data: T, meta?: { page, limit, total } } // Error { error: { code: string, message: string, details?: unknown } } ``` Never mix `data` and `error` in the same response. One or the other. ## HTTP Status Codes | Method | Success | Common Errors | | ------ | ---------------------------- | --------------------------------- | | GET | `200` with data | `404` not found | | POST