Good API design is about anticipating how your API will grow and be consumed over years.
Naming Conventions
- **Resources are nouns**: `/users`, `/orders`, `/products`
- **Plural by default**: `/users/123` not `/user/123`
- **Actions use HTTP methods**: GET, POST, PUT, PATCH, DELETE
- **Nested for relationships**: `/users/123/orders`
Versioning
Three approaches: 1. URL path: `/api/v1/users` 2. Header: `Accept: application/vnd.api.v1+json` 3. Query param: `/api/users?version=1`
I prefer URL path versioning — it's explicit, easy to discover, and simple to route.
Error Responses
Consistent error shapes save hours of debugging: ```json { "error": { "code": "VALIDATION_ERROR", "message": "The given data was invalid.", "details": [ { "field": "email", "message": "The email field is required." } ] } } ```