andvl1/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