api-design

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

• Plural nouns, kebab-case, max 2-level nesting
• Correct HTTP methods and status codes
• RFC 7807 Problem Details for errors
• @Valid on all @RequestBody
• Global @RestControllerAdvice exception handler
• Pagination on list endpoints (cursor preferred)
• Sort field whitelist
• API version in URL path
• Location header on 201 responses
• Rate limiting with standard headers
• OpenAPI docs (@Operation, @ApiResponse)
• Idempotency keys on mutation endpoints
• Bulk operations capped (max 100)
• Async ops use 202 + polling

References

• references/design-patterns.md — Cursor/keyset pagination code, filtering/sorting, field selection, OpenAPI config
• references/operations-docs.md — File upload/download, idempotency, bulk operations, long-running operations

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