REST API Design Principles
URL Structure
GET /api/v1/resources # List all
GET /api/v1/resources/{id} # Get one
POST /api/v1/resources # Create
PUT /api/v1/resources/{id} # Replace
PATCH /api/v1/resources/{id} # Partial update
DELETE /api/v1/resources/{id} # Delete
# Nested resources
GET /api/v1/parents/{id}/children
POST /api/v1/parents/{id}/children
HTTP Status Codes
| Code |
Meaning |
When to Use |
| 200 |
OK |
Successful GET, PUT, PATCH |
| 201 |
Created |
Successful POST (new resource) |
| 204 |
No Content |
Successful DELETE |
| 400 |
Bad Request |
Validation errors, malformed request |
| 401 |
Unauthorized |
Missing or invalid authentication |
| 403 |
Forbidden |
Valid auth but no permission |
| 404 |
Not Found |
Resource doesn't exist |
| 409 |
Conflict |
Duplicate, state conflict |
| 422 |
Unprocessable |
Semantic errors |
| 500 |
Server Error |
Unexpected errors |
Request/Response Design
Collection Response
{
"data": [...],
"pagination": {
"page": 1,
"pageSize": 20,
"totalItems": 150,
"totalPages": 8
}
}
Single Resource Response
{
"id": "uuid",
"name": "Resource Name",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T11:00:00Z"
}
Error Response
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Name is required",
"details": [
{"field": "name", "message": "must not be blank"}
]
}
}
Query Parameters
# Filtering
GET /api/v1/resources?status=active&type=premium
# Sorting
GET /api/v1/resources?sort=createdAt,desc
# Pagination
GET /api/v1/resources?page=1&pageSize=20
# Field selection
GET /api/v1/resources?fields=id,name,status
# Search
GET /api/v1/resources?search=query
Idempotency
- POST with unique identifiers should return existing resource (200) if duplicate
- PUT/DELETE should be idempotent
- Use
Pair<Result, Boolean> pattern to indicate created vs existing
Versioning
- Use URL path versioning:
/api/v1/, /api/v2/
- Version when making breaking changes
- Support old versions during migration period
Security Considerations
- Always validate input at API boundary
- Use parameterized queries (JOOQ handles this)
- Check authorization in service layer
- Never expose internal IDs or sensitive data
- Rate limit public endpoints
ashchupliak