| name | api-design |
| description | REST API design patterns for Spring Boot — HTTP methods, status codes, URL conventions, RFC 7807 ProblemDetail errors, pagination, versioning, validation, and OpenAPI documentation. Use when designing REST endpoints, choosing HTTP status codes, implementing error responses, adding pagination to list APIs, versioning APIs, or generating OpenAPI/Swagger specs.
|
| triggers | {"natural":["api design","error format","pagination design","openapi","rest conventions"],"code":["RFC 7807","ProblemDetail","OpenAPI","Pageable"]} |
| applicability | {"always":false,"triggers":{"files_match":["**/*Controller.java","**/*Handler.java","**/*RouterFunction*.java","**/openapi*.yml","**/openapi*.yaml"],"code_patterns":["@RestController","@RequestMapping","ResponseEntity","ProblemDetail","@Operation","@ApiResponse"],"task_keywords":["endpoint","REST","API","OpenAPI","Swagger","ProblemDetail","pagination design","HTTP status"],"related_rules":["rules/java/api-design.md","rules/java/security.md"]}} |
| relevance_assessment | HIGH 80%+: new endpoint OR contract change OR OpenAPI annotations
MEDIUM 40-79%: existing endpoint behavior tweak, no contract change
LOW 1-39%: caller refactor without endpoint touch
ZERO: no REST surface in scope (verify: grep -r '@RestController' src/main/ = 0)
|
REST API Design Patterns
HTTP Methods & Status Codes
| Method | Purpose | Idempotent | Success Code |
|---|
GET | Read | Yes | 200 |
POST | Create | No | 201 + Location |
PUT | Full replace | Yes | 200 |
PATCH | Partial update | No | 200 |
DELETE | Remove | Yes | 204 |
Key codes: 201 (Created + Location), 202 (Async), 204 (No content), 400 (Validation), 401 (Unauthenticated), 403 (Forbidden), 404 (Not found), 409 (Conflict), 422 (Semantic), 429 (Rate limited).
URL Conventions
- Resource mapping (controller):
/api/${resource}
- Path APIs (method):
/${versioning}/...
- Full URL:
/api/${resource}/${versioning}/...
# Controller: @RequestMapping("/api/users")
GET /api/users/v1 # List
POST /api/users/v1 # Create
GET /api/users/v1/123 # Get by ID
PUT /api/users/v1/123 # Replace
DELETE /api/users/v1/123 # Delete
GET /api/users/v1/123/orders # Nested (max 2 levels)
# Controller: @RequestMapping("/api/orders")
POST /api/orders/v1/123/cancel # Action as sub-resource
Rules: plural nouns, kebab-case, lowercase, no trailing slash, no verbs. Version on method, NOT resource mapping — enables per-resource bumps.
Error Format — RFC 7807
{
"type": "https://api.example.com/problems/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "Request validation failed",
"errors": [{"field": "email", "message": "must be a valid email"}]
}
Enable: spring.mvc.problemdetail.enabled: true. Use @RestControllerAdvice with ProblemDetail.
Pagination
| Type | Best For | Notes |
|---|
Offset (page=0&size=20) | Admin UIs | Simple; slow at large offsets |
| Cursor (opaque token) | Feeds, infinite scroll | Consistent; no drift |
Keyset (afterId=X) | Large datasets | Fastest; needs composite index |
Cap size at 100. Prefer cursor/keyset.
Versioning
Version in method path: /api/{resource}/{version}/.... v1 is forever — backward compatible. Optional fields for minor changes. Breaking changes = new version. Use Sunset + Deprecation headers.
Validation & Rate Limiting
@Valid on all @RequestBody. Bean Validation: @NotBlank, @Email, @Size, @NotNull.- Whitelist sort fields to prevent injection.
- Rate limit headers:
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After.
Checklist
References
Related Skills
- summer-rest — Summer Framework handler pattern, ResponseFactory, exception handling
- spring-webflux-patterns — Controller implementation patterns (MVC + WebFlux)
- spring-security — Rate limiting headers, CORS, authentication for APIs
- architecture — Hexagonal interface layer design for REST endpoints
