A well-designed REST API is intuitive, consistent, and easy to use. A poorly designed API is a nightmare.
URL Conventions¶
REST API Design Best Practices¶
GET /api/v1/users # List GET /api/v1/users/123 # Detail POST /api/v1/users # Create PUT /api/v1/users/123 # Update (full) PATCH /api/v1/users/123 # Update (partial) DELETE /api/v1/users/123 # Delete
❌ Wrong¶
GET /api/getUsers POST /api/deleteUser/123 GET /api/user/123/getOrders
Status Codes¶
- 200: OK (GET, PUT, PATCH)
- 201: Created (POST)
- 204: No Content (DELETE)
- 400: Bad Request (validation)
- 401: Unauthorized (not authenticated)
- 403: Forbidden (no permission)
- 404: Not Found
- 409: Conflict (duplicate)
- 422: Unprocessable Entity
- 429: Too Many Requests
- 500: Internal Server Error
Response Format¶
// Success { “data”: { “id”: 123, “name”: “Jan” } } // Error { “error”: { “code”: “VALIDATION_ERROR”, “message”: “Email is required”, “details”: [{ “field”: “email”, “message”: “Required” }] } } // List with pagination { “data”: […], “meta”: { “total”: 100, “page”: 1, “limit”: 20 } }
Key Takeaway¶
Nouns in URLs, HTTP methods for actions, correct status codes, consistent response format.
restapidesignbest practices