REST API Design
Design RESTful APIs with proper conventions and developer experience.
Resource Naming
# Good - nouns, plural, hierarchical
GET /api/users
GET /api/users/123
GET /api/users/123/orders
POST /api/users
PATCH /api/users/123
DELETE /api/users/123
# Bad - verbs, actions in URL
GET /api/getUsers
POST /api/createUser
POST /api/users/123/delete
HTTP Methods
| Method |
Purpose |
Idempotent |
| GET |
Read resource |
Yes |
| POST |
Create resource |
No |
| PUT |
Replace resource |
Yes |
| PATCH |
Partial update |
Yes |
| DELETE |
Remove resource |
Yes |
Status Codes
| Code |
Meaning |
Use For |
| 200 |
OK |
Successful GET, PATCH |
| 201 |
Created |
Successful POST |
| 204 |
No Content |
Successful DELETE |
| 400 |
Bad Request |
Validation errors |
| 401 |
Unauthorized |
Missing auth |
| 403 |
Forbidden |
Insufficient permissions |
| 404 |
Not Found |
Resource doesn't exist |
| 429 |
Too Many Requests |
Rate limited |
Response Format
{
"data": {
"id": "123",
"type": "user",
"attributes": {
"name": "John",
"email": "john@example.com"
}
},
"meta": {
"requestId": "req_abc123"
}
}
Collection Response
{
"data": [...],
"pagination": {
"page": 1,
"limit": 20,
"total": 150,
"totalPages": 8
},
"links": {
"self": "/api/users?page=1",
"next": "/api/users?page=2"
}
}
Query Parameters
GET /api/products?category=electronics # Filtering
GET /api/products?sort=-price,name # Sorting
GET /api/products?page=2&limit=20 # Pagination
GET /api/products?fields=id,name,price # Field selection
Best Practices
- Use nouns for resources, not verbs
- Version API via URL path (
/api/v1/)
- Return appropriate status codes
- Include pagination for collections
- Document with OpenAPI/Swagger
secondsky