REST API Design, Validation & ControllerAdvice

Use nouns, plural collections, and HTTP verbs for actions; nest only one level for true containment.

• POST /orders creates (201 + Location: /orders/42), GET /orders/42, PUT /orders/42 (full replace), PATCH /orders/42 (partial), DELETE /orders/42.
• GET /orders/42/items for line items; use /items/{id} directly when items have globally unique ids.
• Non-CRUD actions are modelled as sub-resources or state changes: POST /orders/42/cancellation, not POST /cancelOrder.

201 Created (with Location), 204 No Content, 400 (malformed/validation; 422 if you distinguish semantic errors), 404, 409 Conflict, 401, 403, and 504 (or 502/503 depending on cause).

• 401 means "who are you?" (missing/invalid credentials); 403 means "I know you, but no".
• Return 404 instead of 403 when revealing existence of a resource is itself a leak.
• 429 Too Many Requests with Retry-After for rate limiting; 412/428 for conditional-request failures with ETag.

Offset pagination does OFFSET 10000, scanning and discarding rows, and shifting data between requests causes duplicates and skips. Use keyset (cursor) pagination: filter by the last seen sort key.

SELECT * FROM orders
WHERE (created_at, id) < (:lastCreatedAt, :lastId)
ORDER BY created_at DESC, id DESC
LIMIT 20;

• Return an opaque cursor token and a hasNext flag; cap size (e.g., max 100).
• Spring Data offers Pageable (with a count query) and Slice (skips the count), and since Spring Data 3.1 ScrollPosition / Window for keyset scrolling.
• A deterministic unique tie-breaker (id) in the sort is essential.

Require an Idempotency-Key header, store it with the request fingerprint and result under a unique constraint, and return the stored response on replay.

• Insert (key, request_hash, status) first; a duplicate key violates the unique index, so concurrent retries serialize on the DB constraint rather than on application checks.
• Same key with a different body should return 409/422.
• Store the response for a bounded TTL; mark in-progress keys to return 409 or wait.
• Naturally idempotent methods (GET, PUT, DELETE) need no key; POST and PATCH do.

URI versioning (/v1/orders) is the simplest, cache- and debug-friendly, and the most common. Header (X-API-Version) or media type (application/vnd.acme.v2+json) keeps URLs stable but is harder to test in a browser and to route at gateways.

• Prefer additive, backward-compatible changes (new optional fields) to avoid new versions at all; clients must ignore unknown fields.
• Spring Framework 7 / Boot 4 adds first-class API versioning; in Boot 3 use @RequestMapping(headers=...), produces, or path prefixes.
• Plan deprecation: Deprecation and Sunset headers, usage metrics per version.

Usual causes: spring-boot-starter-validation is missing (Boot 2.3+ no longer includes it in starter-web), @Valid is absent on the parameter, or the constraint annotations come from the wrong package (javax.validation instead of jakarta.validation in Boot 3).

record CreateUser(@NotBlank String name, @Email String email, @Min(18) int age) {}

@PostMapping("/users")
ResponseEntity<?> create(@Valid @RequestBody CreateUser body) { ... }

Failure raises MethodArgumentNotValidException -> 400 by default.

Validation does not cascade automatically. Put @Valid on the nested field, and for collection elements use @Valid on the field or type-use constraints such as List<@NotBlank String>.

record OrderRequest(@NotEmpty List<@Valid Item> items, @Valid Address shipping) {}

Without @Valid on shipping, constraints inside Address are ignored. Cascade also does not apply to Map keys unless annotated.

Use validation groups or, more simply, separate DTOs. With groups, constraints name the group and the controller uses @Validated(OnCreate.class).

interface OnCreate {}  interface OnUpdate {}
class UserDto {
    @Null(groups = OnCreate.class) @NotNull(groups = OnUpdate.class) Long id;
    @NotBlank(groups = {OnCreate.class, OnUpdate.class}) String name;
}
@PostMapping ... create(@Validated(OnCreate.class) @RequestBody UserDto d)

Note @Valid cannot select groups; only Spring's @Validated can. Constraints without a group belong to Default and are not checked when only a custom group is requested.

Create an annotation plus a ConstraintValidator; Spring injects beans into validators.

@Constraint(validatedBy = UniqueUsernameValidator.class)
@Target(FIELD) @Retention(RUNTIME)
@interface UniqueUsername { String message() default "taken"; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }

class UniqueUsernameValidator implements ConstraintValidator<UniqueUsername, String> {
    private final UserRepository repo;
    UniqueUsernameValidator(UserRepository repo) { this.repo = repo; }
    public boolean isValid(String v, ConstraintValidatorContext c) { return v == null || !repo.existsByUsername(v); }
}

Pitfalls: check-then-act is a race, so keep a DB unique constraint and map DataIntegrityViolationException to 409; return true for null and let @NotNull handle it; avoid heavy queries in validators on hot paths.

Return ProblemDetail (or ErrorResponse) from handlers, or enable spring.mvc.problemdetails.enabled=true so Spring MVC's standard exceptions render as application/problem+json.

@RestControllerAdvice
class ApiErrors extends ResponseEntityExceptionHandler {
    @ExceptionHandler(OrderNotFound.class)
    ProblemDetail notFound(OrderNotFound e) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, e.getMessage());
        pd.setTitle("Order not found");
        pd.setProperty("orderId", e.getId());
        return pd;
    }
}

Extending ResponseEntityExceptionHandler handles all Spring MVC exceptions uniformly. Never leak stack traces or SQL text in detail.

Within one advice, the handler with the closest exception type (smallest inheritance distance) wins. Across advice beans, @Order/Ordered decides: the first advice (lowest value) that has a matching handler wins, even if a later advice has a closer match.

• Without @Order, advice order is undefined; always set it when advice classes overlap.
• Controller-local @ExceptionHandler methods take precedence over any advice.
• Use basePackages or annotations on @ControllerAdvice to narrow scope.
• A catch-all @ExceptionHandler(Exception.class) should be in the lowest-precedence advice (@Order(Ordered.LOWEST_PRECEDENCE)).

@ControllerAdvice only handles exceptions raised in the DispatcherServlet handler chain. A filter's exception propagates to the container, which forwards to /error handled by BasicErrorController, producing Boot's whitelabel/JSON error body.

Options: catch and write the response in the filter, delegate to HandlerExceptionResolver (resolver.resolveException(req, res, null, ex)) so advice applies, or customize ErrorAttributes. In Spring Security use AuthenticationEntryPoint and AccessDeniedHandler for 401/403.

Entities expose your schema, couple the API to persistence, and trigger runtime problems when serialized.

• Lazy associations cause LazyInitializationException (or N+1 queries) during JSON serialization.
• Bidirectional relations create infinite recursion (StackOverflowError).
• Mass assignment: binding a request into an entity lets clients set role, id, or version.
• Internal fields (password hash) leak; schema changes break clients.
• Use records plus a mapper (MapStruct) or projections.

Plain Jackson fails on unknown properties, but Spring Boot sets FAIL_ON_UNKNOWN_PROPERTIES=false, so unknown fields are silently ignored (typos go unnoticed). Enable spring.jackson.deserialization.fail-on-unknown-properties=true for strict public APIs.

• Primitive int fields default to 0 when missing; use Integer or @NotNull wrapper to detect absence.
• Records deserialize via the canonical constructor (Jackson 2.12+).
• Missing -parameters/no default constructor on classes causes "no Creators" errors.
• @JsonProperty(access = WRITE_ONLY) for password inputs.

Use Boot's auto-configured ObjectMapper, which registers JavaTimeModule and sets WRITE_DATES_AS_TIMESTAMPS=false. If you built your own mapper, register JavaTimeModule and disable that feature.

• Prefer Instant/OffsetDateTime (UTC) on the wire; LocalDateTime has no zone and is ambiguous across clients.
• spring.jackson.time-zone=UTC affects java.util.Date, not Instant.
• Keep the JVM and DB in UTC (hibernate.jdbc.time_zone=UTC).

Boot limits multipart requests to 1 MB per file and 10 MB per request by default (spring.servlet.multipart.max-file-size/max-request-size); exceeding raises MaxUploadSizeExceededException (map to 413). Raise limits deliberately and also enforce a gateway/Tomcat limit.

• Stream to storage (MultipartFile.getInputStream()) instead of getBytes() to avoid loading the file into heap.
• For large files, use pre-signed S3 URLs so bytes bypass your app.
• Validate content type by sniffing bytes, not the client-provided Content-Type or filename; generate your own storage name to prevent path traversal (../).

CORS is enforced only by browsers; the server must answer the preflight OPTIONS request and send Access-Control-Allow-Origin. Configure with @CrossOrigin, a WebMvcConfigurer.addCorsMappings, or, when Spring Security is present, http.cors(Customizer.withDefaults()) with a CorsConfigurationSource bean.

@Bean
CorsConfigurationSource cors() {
    var c = new CorsConfiguration();
    c.setAllowedOrigins(List.of("https://app.example.com"));
    c.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE"));
    c.setAllowCredentials(true);
    var s = new UrlBasedCorsConfigurationSource();
    s.registerCorsConfiguration("/**", c);
    return s;
}

Prefer enforcement at the edge (API gateway, WAF, NGINX) for coarse protection, plus application-level limits per API key or user for fairness. Token bucket allows bursts at a steady refill rate; fixed window is simplest but allows 2x bursts at boundaries; sliding window is smoother.

• Multi-instance apps need a shared store (Redis with Lua/Bucket4j + Redis) or limits are per node.
• Respond 429 with Retry-After and X-RateLimit-* headers.
• Resilience4j RateLimiter limits outgoing calls or in-process throughput, not distributed per-client quotas.
• Implement as a OncePerRequestFilter / HandlerInterceptor keyed on principal, falling back to IP (beware proxies; use trusted forwarded headers).

The container thread is released while the work runs on another executor, then the result is dispatched back to complete the response. This helps when waiting on slow I/O, but the work still occupies some thread unless the downstream call is truly non-blocking.

• Async dispatch re-runs filters; security context is propagated by Spring Security's async support.
• Default executor for MVC async is a simple non-pooling SimpleAsyncTaskExecutor unless Boot's applicationTaskExecutor is used; configure spring.mvc.async.request-timeout.
• Timeouts raise AsyncRequestTimeoutException (503).
• With virtual threads (spring.threads.virtual.enabled=true, Java 21), plain blocking controllers are often simpler.

Mistakes: calling .block() inside a reactive pipeline on a Netty event-loop thread (throws IllegalStateException: block()/blockFirst()/blockLast() are blocking), no timeouts, and unbounded connection pool wait.

WebClient client = builder
    .clientConnector(new ReactorClientHttpConnector(
        HttpClient.create().responseTimeout(Duration.ofSeconds(3))))
    .build();

Order o = client.get().uri("/orders/{id}", id)
    .retrieve().bodyToMono(Order.class)
    .timeout(Duration.ofSeconds(5)).block(); // fine on a servlet thread

• Set connect/response/read timeouts and pool limits (ConnectionProvider).
• Use onStatus to map 4xx/5xx to domain exceptions; retrieve() throws WebClientResponseException by default.
• Spring 6.1 / Boot 3.2 added RestClient, a synchronous fluent client that avoids WebFlux for blocking apps.

Return an ETag (often the entity's @Version) on GET, require If-Match on PUT/PATCH, and respond 412 Precondition Failed on mismatch (or 428 if the header is missing).

• JPA @Version makes the update fail with ObjectOptimisticLockingFailureException if the row changed; map it to 409/412.
• ShallowEtagHeaderFilter computes ETag from the body for caching (If-None-Match -> 304) but does not save the work of computing the response and is not a concurrency control.

Whitelist sortable and filterable fields and map them to known columns; never concatenate request values into JPQL/SQL or accept arbitrary property paths in Sort.

• Spring Data Pageable with sort=password,asc happily sorts by any property unless you validate it; this leaks info via ordering.
• Use bind parameters, Specifications/QueryDSL with enum-based criteria, and cap page size.
• Authorize per row (tenant/owner predicate in the query), not just per endpoint.

Accept the request, return 202 Accepted with a Location header pointing at a status resource, run the work asynchronously (queue/worker), and let the client poll GET /reports/{id} (status, progress, result URL) or receive a webhook.

• Do not hold the HTTP connection; gateways and load balancers time out at 30-60 s.
• Persist job state so it survives restarts; make the job idempotent and resumable.
• Return 303 See Other to the result when complete, or Retry-After while pending.

415 Unsupported Media Type: the Content-Type of the request is not accepted by consumes or no HttpMessageConverter can read it (for example, sending form data to @RequestBody JSON, or a missing Content-Type: application/json). 406 Not Acceptable: the Accept header cannot be satisfied by produces.

• @RequestBody needs a JSON converter (Jackson on the classpath) and a header matching.
• @RequestParam/@ModelAttribute bind form data, not JSON.
• Suffix/path-extension negotiation is removed in Spring 6.

Use @WebMvcTest(UserController.class) with MockMvc, mocking the service; it loads only web-layer beans, including @ControllerAdvice.

mvc.perform(post("/users").contentType(APPLICATION_JSON).content("{\"name\":\"\"}"))
   .andExpect(status().isBadRequest())
   .andExpect(jsonPath("$.title").value("Bad Request"));

Expected: 400 with a problem body when name is blank. Use @MockBean (or @MockitoBean in 6.2+) for services, and @Import custom advice if needed.

Normalize at the boundary (trim, lowercase email) before validation and uniqueness checks, and enforce the invariant in the database with a unique index on the normalized value (or a case-insensitive collation / citext).

• Jackson: custom deserializer or a compact canonical constructor in a record.
• Validators cannot be the sole guarantee: concurrent requests race, so catch DataIntegrityViolationException and return 409.
• Apply consistent Unicode normalization (NFKC) for usernames to avoid lookalike duplicates.