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
