api-design-patterns

# API Design Patterns ## URL Structure ``` # Resource naming: plural nouns, lowercase, hyphenated GET /api/v1/users # list POST /api/v1/users # create GET /api/v1/users/:id # read one PATCH /api/v1/users/:id # partial update PUT /api/v1/users/:id # full replace DELETE /api/v1/users/:id # delete # Nested resources (max 2 levels) GET /api/v1/users/:userId/orders POST /api/v1/users/:userId/orders GET /api/v1/users/:userId/orders/:orderId # Actions that don't fit CRUD — use verbs as sub-resources POST /api/v1/users/:id/activate POST /api/v1/orders/:id/cancel POST /api/v1/auth/refresh POST /api/v1/auth/logout ``` ## Standard Response Envelope ```typescript // types/api-response.ts export interface ApiResponse<T> { success: boolean data: T | null error: ApiError | null meta?: ResponseMeta } export interface ApiError { code: string // machine-readable, stable: 'USER_NOT_FOUND' message: string // human-readable details?: Record<string, string[]> // field validation errors } export interface ResponseMeta { total: number page: number limit: number pages: number } // Success { "success": true, "data": { "id": 1, "name": "Jane" }, "error": null } // Error { "success": false, "data": null, "error": { "code": "VALIDATION_ERROR", "message": "Invalid request body", "details": { "email": ...