api-design

When to Use

• Designing a new REST API
• Reviewing or refactoring existing endpoints
• Defining error responses, pagination, or versioning strategy
• Writing OpenAPI/Swagger documentation
• Implementing HATEOAS or rate limiting

Instructions

1. Resource Naming

Rules:

• Plural nouns, not verbs: /users not /getUsers
• Consistent casing: kebab-case or snake_case, not mixed
• Nest by ownership, not by convenience: max 2 levels deep
• Verbs only for actions that are not CRUD: POST /orders/42/cancel

2. Versioning

Recommendation: URI path for public APIs, header for internal/microservices.

3. Error Handling (RFC 9457 / application/problem+json)

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/order/invalid-status",
  "title": "Invalid order status transition",
  "status": 422,
  "detail": "Cannot transition order 42 from 'shipped' to 'pending'.",
  "instance": "/orders/42",
  "timestamp": "2025-05-31T10:30:00Z"
}

Always use consistent error envelope. Map HTTP status codes semantically:

Never return 5xx for client errors or 4xx for server faults.

4. Pagination

Cursor-based (preferred for large datasets):

GET /users?cursor=eyJpZCI6NDJ9&limit=20

{
  "data": [...],
  "pagination": {
    "next": "eyJpZCI6NjJ9",
    "limit": 20
  }
}

Offset-based (acceptable for small/admin datasets):

GET /users?page=1&size=20

{
  "data": [...],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 150,
    "total_pages": 8
  }
}

5. HATEOAS

Guide clients via links in responses — they don't hardcode URLs:

GET /orders/42

{
  "id": 42,
  "status": "pending",
  "_links": {
    "self": { "href": "/orders/42" },
    "cancel": { "href": "/orders/42/cancel", "method": "POST" },
    "pay": { "href": "/orders/42/pay", "method": "POST" }
  }
}

Spring Boot: org.springframework.boot:spring-boot-starter-hateoas

6. Rate Limiting

Response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1717142400

OpenAPI / SpringDoc

Use springdoc-openapi (springdoc-openapi-starter-webmvc-ui for Boot 3+):

@Operation(summary = "List all users", description = "Returns paginated list of active users")
@ApiResponse(responseCode = "200", description = "Users found")
@ApiResponse(responseCode = "401", description = "Unauthorized")
@GetMapping
public ResponseEntity<Page<UserResponse>> listUsers(
    @Parameter(description = "Cursor for pagination") @RequestParam(required = false) String cursor
) { ... }

Annotate every endpoint — don't rely on auto-generated names.

Anti-Patterns

• /api prefix on every route — api.example.com or gateway takes care of it
• Nested resources beyond 3 levels — /a/1/b/2/c/3/d/4 is unreadable; use query params
• Returning 200 with error in body — use correct HTTP status codes
• Leaking stack traces in production responses — use @ControllerAdvice to sanitize
• Breaking existing clients without versioning or migration window
• /getAllUsers — REST uses HTTP methods, not verbs in the URL

Commands

# Generate OpenAPI spec at runtime
curl localhost:8080/v3/api-docs | jq .

# OpenAPI UI
open http://localhost:8080/swagger-ui.html