A Practical Guide to REST API Design

I've consumed and built a lot of APIs. The good ones share common patterns. Here are the conventions I follow. ## Resource Naming Use nouns, not verbs. The HTTP method is the verb. ``` GET /api/projects # List projects POST /api/projects # Create project GET /api/projects/123 # Get project 123 PUT /api/projects/123 # Update project 123 DELETE /api/projects/123 # Delete project 123 ``` ## Consistent Error Responses Every error should return the same shape: ```json { "error": { "code": "validation_error", "message": "Invalid input", "details": { "email": ["Must be a valid email address"] } } } ``` ## Pagination Never return unbounded lists. Always paginate: ```json { "data": [...], "meta": { "page": 1, "per_page": 20, "total": 150 } } ``` ## Versioning Use URL versioning (`/api/v1/...`) for public APIs. Headers are harder to test and debug. ## Authentication For user-facing APIs, JWT tokens work well. For server-to-server, API keys are simpler. Always require HTTPS. ## The Basics That Matter - Return proper HTTP status codes - Use JSON everywhere - Document your API (OpenAPI/Swagger) - Rate limit your endpoints - Log everything Good APIs are predictable. If a developer can guess the next endpoint's shape, you've done your job.