Spring Boot Web API Layer

REST API implementation patterns for Spring Boot 4 with Spring MVC and WebFlux.

Technology Selection

With Virtual Threads (Java 21+), MVC handles high concurrency without WebFlux complexity.

Core Workflow

1. Create controller → @RestController with @RequestMapping base path
2. Define endpoints → @GetMapping, @PostMapping, etc.
3. Add validation → @Valid on request body, custom validators
4. Handle exceptions → @RestControllerAdvice with ProblemDetail
5. 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.jackson package (not com.fasterxml.jackson)
• ProblemDetail enabled by default: spring.mvc.problemdetails.enabled=true
• API Versioning via version attribute in mapping annotations
• @MockitoBean replaces @MockBean in 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

Critical Reminders

1. Controllers are thin — Delegate to services, no business logic
2. Validate at the boundary — @Valid on all request bodies
3. Use ProblemDetail — Structured errors for all exceptions
4. Version from day one — Easier than retrofitting
5. @MockitoBean not @MockBean — Spring Boot 4 change