designing-apislisted

# Designing APIs ### When to Load - **Trigger**: Designing REST or GraphQL endpoints, API contracts, versioning, request/response formats - **Skip**: Internal-only code with no API surface ## API Design Workflow Copy this checklist and track progress: ``` API Design Progress: - [ ] Step 1: Define resources and relationships - [ ] Step 2: Design endpoint structure - [ ] Step 3: Define request/response formats - [ ] Step 4: Plan error handling - [ ] Step 5: Add authentication/authorization - [ ] Step 6: Document with OpenAPI spec - [ ] Step 7: Validate design against checklist ``` ## REST API Design ### URL Structure ``` # Resource-based URLs (nouns, not verbs) GET /users # List users GET /users/:id # Get user POST /users # Create user PUT /users/:id # Replace user PATCH /users/:id # Update user DELETE /users/:id # Delete user # Nested resources GET /users/:id/orders # User's orders POST /users/:id/orders # Create order for user # Query parameters for filtering/pagination GET /users?role=admin&status=active GET /users?page=2&limit=20&sort=-createdAt ``` ### HTTP Status Codes | Code | Meaning | Use Case | | ---- | ----------------- | -------------------------- | | 200 | OK | Successful GET, PUT, PATCH | | 201 | Created | Successful POST | | 204 | No Content | Successful DELETE | | 400 | Bad Reques