api-design

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