REST APIs with Spring MVC
Arena's 18 endpoints are the contract the other two projects depend on. This module covers HTTP from first principles, how to design a REST API, what happens inside Spring MVC for each request, and how Arena handles validation, errors, pagination, idempotency, JSON and documentation. It also covers the client side, because Telemetry and the Judge both call Arena.
By the end you can answer
- "Which HTTP methods are safe and which are idempotent? How did you make a POST idempotent?"
- "401 vs 403? 400 vs 409 vs 422?"
- "Walk me through what Spring does with a request, from the socket to your controller."
- "Why DTOs instead of returning entities?"
- "How do you validate input and report errors consistently?"
- "Offset vs keyset pagination?"
- "What is MapStruct and why not map by hand or with reflection?"
1. HTTP in five minutes
HTTP is a request/response text protocol. A client sends a request: a method, a path, headers and an optional body. The server replies with a response: a status code, headers and an optional body.
POST /api/v1/matches HTTP/1.1
Host: localhost:8080
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9... <- a JWT (module 05)
Content-Type: application/json
{"externalId":"m-42","gameMode":"FFA","mapName":"Dust","startedAt":"...","endedAt":"...","participants":[...]}
HTTP/1.1 201 Created
Location: /api/v1/matches/6f1c... <- where the new resource lives
Content-Type: application/json
{"id":"6f1c...","externalId":"m-42", ...}
Methods: safe and idempotent
Safe means the request doesn't change server state. Idempotent means doing it twice has the same effect as doing it once. Idempotency is what makes retries safe after a timeout, when you don't know whether the first attempt worked.
| Method | Purpose | Safe | Idempotent | Arena example |
|---|---|---|---|---|
| GET | Read | Yes | Yes | GET /players/{id} |
| POST | Create, or trigger an action | No | No (by default) | POST /matches, POST /auth/login |
| PUT | Replace the whole resource | No | Yes | (not used) |
| PATCH | Change part of a resource | No | Not guaranteed | PATCH /players/me (display name, country) |
| DELETE | Remove | No | Yes | (not used: the audit log is append-only) |
Status codes you must know cold
| Code | Meaning | When Arena returns it |
|---|---|---|
| 200 OK | Success | Reads; POST /matches when the externalId was already recorded (a replay) |
| 201 Created | A new resource was made; a Location header says where | Register, a new match, a new moderation action, a new appeal |
| 400 Bad Request | The request itself is malformed or invalid | VALIDATION_FAILED, MALFORMED_REQUEST (bad JSON) |
| 401 Unauthorized | "I don't know who you are": missing, invalid or expired credentials | UNAUTHENTICATED, INVALID_CREDENTIALS, INVALID_REFRESH_TOKEN, REFRESH_TOKEN_REUSED |
| 403 Forbidden | "I know who you are, and you're not allowed" | FORBIDDEN (wrong role), ACCOUNT_SUSPENDED |
| 404 Not Found | No such resource | PLAYER_NOT_FOUND, MATCH_NOT_FOUND, PLAYER_NOT_RANKED |
| 409 Conflict | The request conflicts with the current state | USERNAME_TAKEN, INVALID_STATE_TRANSITION, CONCURRENT_MODIFICATION, APPEAL_ALREADY_DECIDED |
| 422 Unprocessable Content | Syntactically fine, but violates a business rule | CONFIDENCE_TOO_LOW, PLAYER_NOT_ELIGIBLE, INVALID_SOURCE |
| 429 Too Many Requests | Rate limited; may carry Retry-After | (from Claude; the Judge honours Retry-After) |
| 500 / 503 | Server error / temporarily unavailable | INTERNAL_ERROR, never with a stack trace |
Telemetry's ArenaMatchClient treats 429, 5xx, timeouts and connection failures as retryable (the next attempt might work) and 400, 404, 409, 422 as non-retryable (retrying the same request cannot change the answer, so it goes to the dead-letter topic). A 401 triggers one re-login and one retry. Correct status codes on the server make correct retry decisions possible on the client. That is a strong point to make.
2. Designing a REST API
REST (Representational State Transfer) is a style, not a standard. The practical rules:
- Resources are nouns identified by URIs:
/players/{id},/matches/{id}. The HTTP method is the verb, so it'sPOST /matches, notPOST /createMatch. - Hierarchy for ownership:
/players/{id}/matchesmeans "this player's matches". - Model actions as resources when they need a record: a moderation action is created with
POST /moderation/players/{id}/actionsrather thanPOST /players/{id}/ban. Every action becomes a stored, auditable thing with its own id. Same forPOST /appeals/{id}/decision. - Stateless: every request carries everything the server needs (the JWT), so any instance can serve any request and the service scales horizontally.
- Version the contract:
/api/v1. Breaking changes go to/v2while old clients keep working. - Consistent errors (section 6) and consistent pagination (section 7).
The 18 Arena endpoints (see the project guide) follow these rules: auth (3), players (4), matches (3), leaderboard (2), moderation (3), appeals (3).
3. Making POST idempotent: the externalId
The Telemetry bridge posts each finished match. If the network drops after Arena committed but before the response arrived, the bridge cannot know whether the match was saved, so it retries. Without protection, ratings would be applied twice.
The solution is an idempotency key chosen by the client: each match carries a unique externalId, stored in a column with a UNIQUE constraint.
@PostMapping("/matches")
@PreAuthorize("hasRole('SERVICE')")
public ResponseEntity<MatchResponse> recordMatch(@AuthenticationPrincipal Jwt jwt,
@Valid @RequestBody RecordMatchRequest request) {
MatchService.RecordResult result = matchService.recordMatch(request, CurrentUser.id(jwt));
if (result.created()) {
return ResponseEntity.created(URI.create("/api/v1/matches/" + result.match().id()))
.body(result.match()); // 201 + Location
}
return ResponseEntity.ok(result.match()); // 200: replay, nothing changed
}
Inside the service, the first step is "does a match with this externalId exist? If yes, return it". There is still a race: two identical requests arriving at the same moment can both see "no" and both try to insert. The database's unique constraint makes exactly one insert win. The loser's transaction fails with a DataIntegrityViolationException, and MatchService catches it after the rollback, looks up the winner's match and returns it with 200. Module 07 explains why this needs TransactionTemplate.
"The client sends an idempotency key, the externalId. A check-then-insert isn't enough on its own because of races, so the real guarantee is the unique constraint. When a concurrent duplicate loses, I catch the violation after rollback and answer 200 with the winner's match instead of a 500. That turns at-least-once delivery from Kafka into exactly-once effects in the database."
4. What Spring MVC does with a request
HTTP request
│
▼
Tomcat (embedded web server) ── one (virtual) thread per request
│
▼
Servlet filter chain ── Spring Security lives here: authenticate JWT, reject 401/403 early
│
▼
DispatcherServlet ── the "front controller"
│ 1. HandlerMapping: which controller method matches "POST /api/v1/matches"?
│ 2. Argument resolvers: @PathVariable, @RequestParam, @RequestBody (JSON → record via Jackson),
│ @AuthenticationPrincipal Jwt
│ 3. Validation: @Valid on the body, @Validated method constraints
│ 4. Method security proxy: @PreAuthorize("hasRole('SERVICE')")
▼
Your controller method ──► service ──► repository ──► database
│
▼
Return value → HttpMessageConverter (Jackson) → JSON body
│
(on exception) → @RestControllerAdvice → ProblemDetail JSON
@PreAuthorize
@Valid @RequestBody is checked while resolving arguments, before the method-security proxy runs. So a test that checks "a PLAYER gets 403 on POST /matches" must send a valid body; an invalid body produces 400 first. Knowing the order of the pipeline explains this immediately.
Controllers stay thin
Arena's controllers only translate HTTP into method calls: read the path, the body and the caller's id from the JWT, call the service, choose the status code. All rules live in services, which can be tested without HTTP. CurrentUser.id(jwt) extracts the caller's UUID from the token's sub claim.
5. DTOs: never expose your entities
A DTO (data transfer object) is the shape of data on the wire. Arena has separate request and response records in each feature's dto/ package. Why not just return the Player entity?
- Leaking data:
PlayerhaspasswordHashandemail. A DTO includes only what that endpoint should show. For example,emailappears only when you look at yourself. - Mass assignment: binding a request straight onto an entity lets a client set fields it shouldn't, such as
roleorrating.UpdateProfileRequestcontains only display name and country. - Decoupling: the database schema can change without breaking the API contract, and the reverse.
- Lazy loading: serialising an entity can trigger database queries for lazy relationships, or fail outside a transaction (module 07). Arena sets
spring.jpa.open-in-view: false, so this fails loudly instead of quietly running extra queries.
6. Validation in layers
Layer 1: Bean Validation on the request record
public record RecordMatchRequest(
@NotBlank @Size(max = 64) String externalId,
@NotNull GameMode gameMode,
@NotBlank @Size(max = 40) String mapName,
@NotNull Instant startedAt,
@NotNull Instant endedAt,
@NotEmpty @Size(min = 2, max = 100) @Valid List<ParticipantRequest> participants) {}
@Valid on the list makes validation cascade into each ParticipantRequest. A violation throws MethodArgumentNotValidException, which the handler turns into a 400 with a list of field errors.
Layer 2: method parameters
@Validated on the controller enables constraints on simple parameters: @RequestParam(defaultValue = "20") @Min(1) @Max(100) int size. A violation becomes a HandlerMethodValidationException, also mapped to 400. The @Max(100) stops a client from asking for a million rows.
Layer 3: cross-field business rules in the service
Annotations check one field at a time. MatchService.validateRequest checks rules that span fields: endedAt after startedAt; no duplicate players; placements form exactly the set 1..n; headshots ≤ kills; shots hit ≤ shots fired.
Layer 4: the database
CHECK constraints in V1__init.sql repeat the critical rules (headshots <= kills, ended_at > started_at, valid enum values). If a future code path forgets a check, the database still refuses bad data. This is defence in depth.
7. One error format everywhere: ProblemDetail
RFC 9457 "Problem Details for HTTP APIs" (it replaced RFC 7807) standardises a JSON error body with the content type application/problem+json. Spring has a ProblemDetail class for it. Every non-2xx response from Arena looks like this:
HTTP/1.1 422
Content-Type: application/problem+json
{
"type": "https://fairplay.dev/errors/confidence-too-low",
"title": "Confidence too low",
"status": 422,
"detail": "Service BAN confidence must be at least 0.80",
"instance": "/api/v1/moderation/players/6f1c.../actions",
"code": "CONFIDENCE_TOO_LOW" <- stable, machine-readable
}
The extra code field is the part clients program against. Text in detail may change; CONFIDENCE_TOO_LOW never will. Validation errors add an errors array of {field, message}.
How it is wired
ErrorCodeenum: each code carries its HTTP status and title.ApiException(ErrorCode, detail): thrown by services for any business failure.GlobalExceptionHandler: a@RestControllerAdvicethat extendsResponseEntityExceptionHandler(so Spring's own exceptions, such as malformed JSON, missing parameters, wrong method and unknown path, also become problems), with@ExceptionHandlermethods forApiException,AccessDeniedException, constraint violations, optimistic-lock failures and data-integrity violations. A final catch-all forExceptionlogs the error and returns a generic 500.server.error.include-stacktrace: never: stack traces reveal internals (library versions, class names, sometimes data) and help attackers.
An invalid or missing JWT is rejected inside Spring Security's filter chain, which runs before the DispatcherServlet, so @RestControllerAdvice never sees it. Arena therefore plugs ProblemAuthenticationEntryPoint (for 401) and ProblemAccessDeniedHandler (for 403) into the security configuration. Both write the same ProblemDetail JSON directly to the response. Without them, security errors would have a different shape from every other error.
Registration first checks existsByUsernameIgnoreCase. Two simultaneous registrations of "Alice" and "alice" can both pass that check. The database's unique index ux_players_username_lower (on lower(username)) rejects the second insert, and handleDataIntegrity inspects the constraint name in the error message to answer 409 USERNAME_TAKEN instead of a 500. Any other integrity violation is logged and becomes a generic 500.
8. Pagination
Lists must never be unbounded. Arena's list endpoints take page and size (default 20, max 100) and return a PageResponse<T> record:
{ "content": [ ... ], "page": 0, "size": 20, "totalElements": 1342, "totalPages": 68 }
Why wrap Spring Data's Page instead of returning it? Its JSON form is an implementation detail with many extra fields, and Spring itself warns against serialising PageImpl directly. A small record of your own is a stable contract.
Offset pagination (LIMIT 20 OFFSET 40000) | Keyset / cursor (WHERE id > :last ORDER BY id LIMIT 20) | |
|---|---|---|
| Jump to page N | Yes | No (only "next") |
| Cost of deep pages | The database still reads and discards all skipped rows: O(offset) | Uses the index to start at the cursor: constant |
| Stable under inserts | No (rows shift between pages) | Yes |
| In Arena | API list endpoints (human-sized pages) | LeaderboardRebuilder streaming a million rows in batches of 10,000 |
The public leaderboard uses offset and limit too, but against Redis (ZREVRANGE by rank), which can jump to a rank in O(log N), so deep pages stay cheap (module 08).
9. JSON with Jackson 3
Jackson converts Java objects to JSON and back. Spring MVC uses it automatically for @RequestBody and return values.
- Records serialise by component name; deserialisation uses the canonical constructor.
Instantis written as an ISO-8601 string such as"2026-11-19T10:15:30Z", always in UTC.- Enums are written by name (
"BANNED"), which is why enum values are contracts. @JsonInclude(NON_NULL)omits null fields.MatchEventuses it so a SHOT event doesn't carry empty movement fields.- Tolerant reader: Telemetry's and the Judge's mappers disable
FAIL_ON_UNKNOWN_PROPERTIES, so a producer can add a field without breaking consumers (the "be liberal in what you accept" side of evolution). JsonMapperis immutable and thread-safe once built, so one shared static instance is correct (JsonSerde.MAPPER,JudgeJson.mapper()).
- Packages moved:
tools.jackson.databind.*, while annotations stay incom.fasterxml.jackson.annotation. - The Anthropic Java SDK still uses Jackson 2. The Judge converts tool input by writing it to a string with the SDK's mapper and reading it back with its own. Two major versions coexist because they live in different packages.
- A record with a primitive component (
double score) fails to deserialise when that field is missing in Jackson 3 (a primitive can't be null). The Judge treats such a flag as malformed and dead-letters it. Use a wrapper type (Double) if absence is legal.
10. MapStruct: mapping entities to DTOs
Copying fields from Player to PlayerSummaryResponse by hand is boring and error-prone. MapStruct generates that code at compile time from an interface:
@Mapper(componentModel = "spring")
public interface PlayerMapper {
PlayerSummaryResponse toSummary(Player player);
@Mapping(target = "email", source = "email")
@Mapping(target = "stats", source = "stats")
PlayerDetailResponse toDetail(Player player, String email, PlayerStats stats, PlayerPercentiles percentiles);
}
During compilation, MapStruct's annotation processor writes PlayerMapperImpl, a plain Java class with ordinary getter and constructor calls, registered as a Spring bean (componentModel = "spring").
| Approach | When mapping happens | Speed | Errors found |
|---|---|---|---|
| By hand | Your code | Fast | When a test catches a forgotten field (if one exists) |
| MapStruct | Generated at compile time | Fast (plain calls, no reflection) | At compile time (unmapped target properties produce warnings) |
| ModelMapper / reflection | At runtime via reflection | Slower | At runtime |
Lombok also runs as an annotation processor, generating getters that MapStruct needs to see. pom.xml lists the processors in order: lombok, then lombok-mapstruct-binding, then mapstruct-processor. The JaCoCo config excludes **/*MapperImpl.class from coverage because it is generated code (module 14).
11. Documentation: OpenAPI and Swagger UI
OpenAPI is a standard, machine-readable description of a REST API (paths, parameters, schemas, security). springdoc-openapi generates it from your controllers at runtime:
/v3/api-docs: the JSON specification. Other teams can generate client code from it./swagger-ui.html: an interactive page where you can try every endpoint, including with a bearer token.@Tag(name = "Matches")and@Operation(summary = "Record a completed match")add human-readable descriptions.OpenApiConfigregisters the bearer-token security scheme.
The project notes record that Swagger lists exactly 18 operations, 13 of them secured, a quick way to check the contract against the specification.
12. The client side: calling Arena
Telemetry (simulator and bridge) and the Judge call Arena with Spring's RestClient, a fluent, synchronous HTTP client (Spring 6.1+). With virtual threads, blocking calls are cheap.
// shape of the calls in ArenaMatchClient / ArenaClient (simplified)
http.post().uri("/api/v1/matches")
.contentType(MediaType.APPLICATION_JSON)
.header("Authorization", "Bearer " + token)
.body(summary)
.retrieve() ...
What a production-quality client does, all present in your code:
- Timeouts. The Judge's Arena client uses a 2 s connect timeout and a 5 s read timeout. Without timeouts, one hung server can block threads forever.
- Token caching and lazy login. Log in once, reuse the access token, and log in again on a 401 (token expired), retrying once.
- Classify failures into retryable and non-retryable (section 1 tip). That classification drives Spring Kafka's retry or dead-letter decision in the bridge.
- Resilience: the Judge's Arena client wraps calls in a Resilience4j retry and circuit breaker (module 12).
- Read only what you need: the Judge's tools return compact JSON built from Arena's responses, never the raw response, both to save tokens and to avoid passing on fields the model shouldn't see.
13. Interview questions
What's the difference between 401 and 403? Basic
401 means "not authenticated": no token, a bad signature or an expired token. The client should (re)authenticate. 403 means "authenticated but not authorised": a valid token whose role isn't allowed, such as a PLAYER calling POST /matches, or a suspended account. In Arena, 401s come from the security filter chain via ProblemAuthenticationEntryPoint, and 403s from @PreAuthorize via the access-denied handler or the advice.
When do you use 409 versus 422? Intermediate
409 Conflict is for requests that clash with the resource's current state: a taken username, an illegal state transition (CLEAR on an ACTIVE player), a concurrent modification, an appeal already decided. Retrying won't help until the state changes. 422 is for requests that are well-formed but break a business rule about the request itself: a service BAN without enough confidence, a match including an ineligible (banned) player, the wrong action source for the role. The important thing is to be consistent and document it; clients then key off the stable code field.
How did you make POST /matches idempotent? Intermediate
The client supplies an idempotency key, externalId, with a unique constraint in PostgreSQL. A replay returns 200 with the stored match; a new match returns 201 with a Location header. For two concurrent identical requests, the unique constraint lets exactly one insert win; the loser's transaction rolls back, and I catch the DataIntegrityViolationException outside the transaction (hence TransactionTemplate), look up the winner and return 200. So Kafka's at-least-once delivery from the bridge produces exactly-once effects.
Walk me through a request's path in Spring MVC. Intermediate
Tomcat accepts the connection and runs the servlet filter chain, where Spring Security authenticates the bearer JWT. The DispatcherServlet asks its handler mappings for the matching controller method, resolves the arguments (path variables, query params, the JSON body via Jackson, the Jwt principal), validates @Valid bodies, passes through the method-security proxy for @PreAuthorize, invokes the method, and writes the return value through a message converter as JSON. Exceptions go to the @RestControllerAdvice, which produces ProblemDetail.
Why not return JPA entities from controllers? Basic
They leak sensitive fields (the password hash), allow mass assignment on input, couple the API contract to the schema, and can trigger lazy-loading queries or exceptions during serialisation. Arena uses request and response records per endpoint, mapped with MapStruct, and disables open-in-view so lazy-loading mistakes fail loudly.
How do you make error responses consistent? Intermediate
One format, RFC 9457 ProblemDetail with an extra stable code. Services throw ApiException(ErrorCode, detail); the error-code enum carries status and title; a global @RestControllerAdvice extending ResponseEntityExceptionHandler converts both my exceptions and Spring's (bad JSON, missing parameter, 404, 405). Security errors happen in filters before MVC, so a custom entry point and access-denied handler write the same shape. Stack traces are never returned.
Why wasn't @Valid enough? Where else do you validate? Intermediate
Bean Validation checks single fields. Cross-field rules (placements form 1..n, headshots ≤ kills, end after start) live in the service. Finally the database has CHECK and UNIQUE constraints as a last line of defence, which also handles races the application can't (two concurrent registrations). Each layer catches what the one above can't.
Offset vs keyset pagination: which did you use and why? Deep
Offset for API lists, because humans browse small pages and want page numbers. Keyset for the internal rebuild that streams a million players into Redis: WHERE id > :lastId ORDER BY id LIMIT 10000 uses the primary-key index to start each batch at the right place, so every batch costs the same. With OFFSET, the database would read and discard all earlier rows, so the batches get slower and slower (quadratic overall). Keyset is also stable when rows are inserted concurrently.
Why MapStruct rather than hand-written mapping or ModelMapper? Intermediate
It generates plain mapping code at compile time: no reflection at runtime, so it's as fast as hand-written code, and mistakes such as unmapped target fields show up during the build. The generated implementation is a Spring bean. The cost is an annotation-processor setup (ordering with Lombok via lombok-mapstruct-binding) and excluding the generated *MapperImpl from coverage.
A test expecting 403 for the wrong role got 400. Why? Curveball
Request-body validation happens during argument resolution, before the @PreAuthorize method-security interceptor runs. An invalid body yields 400 before authorisation is even checked. The test must send a valid body to reach the role check.
Your bridge got a 422 from Arena. Should it retry? Curveball
No. A 422 means the request breaks a business rule (for example the match includes a player the Judge just banned: PLAYER_NOT_ELIGIBLE). Sending the same request again gives the same answer, so the bridge throws NonRetryableArenaException and the error handler sends the record straight to match-summaries.DLT. Retryable cases are 429, 5xx, timeouts and connection errors. This is expected behaviour once bans start, not a bug.
What does @JsonIgnoreProperties(ignoreUnknown = true) buy you, and what's the risk? Deep
It makes consumers tolerant of producers adding fields, which is essential for independent deployment. The risk is silent loss when a field is renamed: the old name disappears and the new one is ignored, so you get null with no error. In the Judge, a renamed skillTier would quietly disable high-tier escalation. That's why field names are treated as contracts, and why a schema registry with compatibility checks is the industrial answer.
14. Quick quiz
1. Which method is idempotent but not safe?
PUT changes state (not safe), but repeating it gives the same result (idempotent). DELETE is the same.
2. A request carries a valid PLAYER token and calls a MODERATOR-only endpoint. Status?
Authenticated but not authorised.
3. Why do Arena's security errors need a custom entry point?
Filters run before the DispatcherServlet.
4. What actually prevents a duplicate match when two identical requests race?
Check-then-act races; only the constraint is atomic.
5. MapStruct generates mapping code:
That's why it's fast and catches mistakes early.
6. Deep pages with OFFSET 900000 are slow because:
Keyset pagination avoids that by starting at the cursor through the index.
15. Cheat sheet
- Safe: GET/HEAD. Idempotent: GET, PUT, DELETE. POST becomes idempotent with a client key plus a UNIQUE constraint (
externalId): 201 on create, 200 on replay. - 401 who are you? · 403 not allowed · 409 conflicts with current state · 422 breaks a business rule · 429 slow down · 5xx our fault, retryable.
- Retryable: 429, 5xx, timeouts, connection errors. Non-retryable: 400/404/409/422, sent to the DLT.
- Pipeline: Tomcat → filters (Security) → DispatcherServlet → mapping → argument resolution +
@Valid→@PreAuthorize→ controller → Jackson. - DTO records, never entities. Thin controllers.
- Validation layers: Bean Validation → method params (
@Validated) → service cross-field rules → DB constraints. - Errors: RFC 9457 ProblemDetail + a stable
code;@RestControllerAdvice; a security entry point and denied handler; no stack traces. - Pagination: page/size (max 100) in a
PageResponserecord; keyset for bulk streaming. - Jackson 3:
tools.jackson; tolerant reader; missing primitive fields fail; thread-safe shared mapper. - MapStruct: compile-time mappers; processor order lombok → binding → mapstruct.
- springdoc:
/v3/api-docs,/swagger-ui.html. - Clients: RestClient + timeouts + token reuse + 401 re-login + failure classification + Resilience4j.