Fairplay Interview Prep
Module 04

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.

P1 (server)P2 (client)P3 (client)· about 2 hours

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.

MethodPurposeSafeIdempotentArena example
GETReadYesYesGET /players/{id}
POSTCreate, or trigger an actionNoNo (by default)POST /matches, POST /auth/login
PUTReplace the whole resourceNoYes(not used)
PATCHChange part of a resourceNoNot guaranteedPATCH /players/me (display name, country)
DELETERemoveNoYes(not used: the audit log is append-only)

Status codes you must know cold

CodeMeaningWhen Arena returns it
200 OKSuccessReads; POST /matches when the externalId was already recorded (a replay)
201 CreatedA new resource was made; a Location header says whereRegister, a new match, a new moderation action, a new appeal
400 Bad RequestThe request itself is malformed or invalidVALIDATION_FAILED, MALFORMED_REQUEST (bad JSON)
401 Unauthorized"I don't know who you are": missing, invalid or expired credentialsUNAUTHENTICATED, 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 FoundNo such resourcePLAYER_NOT_FOUND, MATCH_NOT_FOUND, PLAYER_NOT_RANKED
409 ConflictThe request conflicts with the current stateUSERNAME_TAKEN, INVALID_STATE_TRANSITION, CONCURRENT_MODIFICATION, APPEAL_ALREADY_DECIDED
422 Unprocessable ContentSyntactically fine, but violates a business ruleCONFIDENCE_TOO_LOW, PLAYER_NOT_ELIGIBLE, INVALID_SOURCE
429 Too Many RequestsRate limited; may carry Retry-After(from Claude; the Judge honours Retry-After)
500 / 503Server error / temporarily unavailableINTERNAL_ERROR, never with a stack trace
Why the 4xx/5xx split matters to your clients

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:

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.

arena/.../match/MatchController.java
@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.

How to say it

"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
Gotcha from your notes: validation runs before @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?

6. Validation in layers

Layer 1: Bean Validation on the request record

arena/.../match/dto/RecordMatchRequest.java
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

Why security errors need their own handlers

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.

In your projects: turning a race into a clean 409

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 NYesNo (only "next")
Cost of deep pagesThe database still reads and discards all skipped rows: O(offset)Uses the index to start at the cursor: constant
Stable under insertsNo (rows shift between pages)Yes
In ArenaAPI 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.

Jackson 3 gotchas your projects hit
  • Packages moved: tools.jackson.databind.*, while annotations stay in com.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:

arena/.../player/PlayerMapper.java
@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").

ApproachWhen mapping happensSpeedErrors found
By handYour codeFastWhen a test catches a forgotten field (if one exists)
MapStructGenerated at compile timeFast (plain calls, no reflection)At compile time (unmapped target properties produce warnings)
ModelMapper / reflectionAt runtime via reflectionSlowerAt runtime
Build detail: processor order

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:

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:

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 PageResponse record; 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.
Saved in this browser.