REST API Design Principles Skill

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

Agent Skills: REST API Design Principles

Skill Files