typescript-api-design

# API Design Patterns Best practices for designing REST APIs with consistent structure, error handling, and resource patterns. ## Additional References - [references/error-responses.md](./references/error-responses.md) - Detailed error handling examples ## Resource Naming Use consistent, predictable URL patterns: ``` # Collection resources (plural nouns) GET /api/v1/users # List users POST /api/v1/users # Create user GET /api/v1/users/:id # Get user PUT /api/v1/users/:id # Update user (full) PATCH /api/v1/users/:id # Update user (partial) DELETE /api/v1/users/:id # Delete user # Nested resources GET /api/v1/users/:userId/posts # List user's posts POST /api/v1/users/:userId/posts # Create post for user GET /api/v1/users/:userId/posts/:postId # Get specific post # Actions (use verbs sparingly) POST /api/v1/users/:id/activate # Activate user POST /api/v1/posts/:id/publish # Publish post POST /api/v1/invoices/:id/send # Send invoice ``` ### Guidelines - Use plural nouns for collections (`/users`, not `/user`) - Use lowercase with hyphens for multi-word resources (`/ledger-accounts`) - Avoid deep nesting (max 2 levels: `/users/:id/posts/:id`) - Use query parameters for filtering, sorting, pagination - Use verbs only for actions that don't fit CRUD (activate, publish, send) ## API Versioning Version APIs in the URL path: ``` /api/v1/us...