| name | spring-boot-web-api |
| description | Spring Boot 4 REST API implementation patterns. Use when creating REST controllers, request validation, exception handlers with ProblemDetail (RFC 9457), API versioning, content negotiation, or WebFlux reactive endpoints. Covers @RestController patterns, Bean Validation 3.1, global error handling, and Jackson 3 configuration. |
Spring Boot Web API Layer
REST API implementation patterns for Spring Boot 4 with Spring MVC and WebFlux.
Technology Selection
| Choose | When |
|---|---|
| Spring MVC | JPA/JDBC backend, simpler debugging, team knows imperative style |
| Spring WebFlux | High concurrency (10k+ connections), streaming, reactive DB (R2DBC) |
With Virtual Threads (Java 21+), MVC handles high concurrency without WebFlux complexity.
Core Workflow
- Create controller →
@RestControllerwith@RequestMappingbase path - Define endpoints →
@GetMapping,@PostMapping, etc. - Add validation →
@Validon request body, custom validators - Handle exceptions →
@RestControllerAdvicewithProblemDetail - Configure versioning → Native API versioning (Spring Boot 4)
Quick Patterns
See EXAMPLES.md for complete working examples including:
- REST Controller with CRUD operations and pagination (Java + Kotlin)
- Request/Response DTOs with Bean Validation 3.1
- Global Exception Handler using ProblemDetail (RFC 9457)
- Native API Versioning with header configuration
- Jackson 3 Configuration for custom serialization
- Controller Testing with @WebMvcTest
Spring Boot 4 Specifics
- Jackson 3 uses
tools.jacksonpackage (notcom.fasterxml.jackson) - ProblemDetail enabled by default:
spring.mvc.problemdetails.enabled=true - API Versioning via
versionattribute in mapping annotations - @MockitoBean replaces
@MockBeanin tests
Detailed References
- Examples: See EXAMPLES.md for complete working code examples
- Troubleshooting: See TROUBLESHOOTING.md for common issues and Boot 4 migration
- Controllers & Validation: See references/controllers.md for validation groups, custom validators, content negotiation
- Error Handling: See references/error-handling.md for ProblemDetail patterns, exception hierarchy
- WebFlux Patterns: See references/webflux.md for reactive endpoints, functional routers, WebTestClient
Anti-Pattern Checklist
| Anti-Pattern | Fix |
|---|---|
| Business logic in controllers | Delegate to application services |
| Returning entities directly | Convert to DTOs |
| Generic error messages | Use typed ProblemDetail with error URIs |
| Missing validation | Add @Valid on @RequestBody |
| Blocking calls in WebFlux | Use reactive operators only |
| Catching exceptions silently | Let propagate to @RestControllerAdvice |
Critical Reminders
- Controllers are thin — Delegate to services, no business logic
- Validate at the boundary —
@Validon all request bodies - Use ProblemDetail — Structured errors for all exceptions
- Version from day one — Easier than retrofitting
@MockitoBeannot@MockBean— Spring Boot 4 change