REST API Design That Developers Love
URL Structure
- Use nouns, not verbs: /users not /getUsers
- Use plural names: /users not /user
- Nest for relationships: /users/123/orders
- Use lowercase with hyphens: /order-items
HTTP Methods
| Method | Purpose | Example |
|---|---|---|
| GET | Read data | GET /users |
| POST | Create data | POST /users |
| PUT | Full update | PUT /users/123 |
| PATCH | Partial update | PATCH /users/123 |
| DELETE | Remove data | DELETE /users/123 |
Error Handling
Return consistent error responses with:
- HTTP status code (400, 401, 403, 404, 500)
- Error message (human-readable)
- Error code (machine-readable)
- Details (validation errors)
Pagination
For list endpoints, always paginate:
- Use cursor-based pagination for large datasets
- Use offset/limit for simple cases
- Include total count in response
- Return next/previous page links
Authentication
- Use JWT or session tokens
- Send tokens in Authorization header
- Implement refresh tokens for long sessions
- Rate limit authentication endpoints
Versioning
- Use URL versioning: /api/v1/users
- or Header versioning: Accept: application/vnd.api+json;version=1
Need a well-designed API? I build production-ready APIs with Node.js.