In Part 1 I set out to turn a legacy Java library app into a peer-to-peer platform. In Part 2 I made the persistence real — PostgreSQL, Flyway, tests on the real engine. But the app still had a problem: it had a solid service layer and a real database, and nothing a client could actually call.
Phase 2 fixed that. And I should be honest about where I started: I had never worked with Spring controllers before. I didn't learn controllers by implementing four of them at once. I learned one — the Catalog controller, done properly, as a guide example — and then generalized the pattern to the rest.
The design decision first: entities never cross the wire
Before any controller existed, one rule was settled: controllers return thin response records, never JPA entities. The app runs with open-in-view=false and the associations on BookCopy are LAZY, so returning an entity would either serialize a lazy proxy or blow up trying. A record carries exactly what the client needs and nothing it shouldn't see.
The clearest example is the copy response:
public record BookCopyResponse(
Long id,
Long bookId,
Long ownerId,
CopyVisibility visibility,
boolean isAvailable,
BookCondition condition,
String barcode,
int timesBorrowed,
LocalDate acquiredDate
) {
}
No owner name, no nested book object — just ids. That closed a lazy-loading caveat that had been hanging over the project since the first review: an earlier design wanted the owner's name in the response, which would have forced a lazy load on every copy serialization. Ids only, and the client asks for the member if it needs the name.
Shipped: four controllers, 44 tests, five PRs
Catalog — 22 tests (PR #17): 11 endpoints — create, fetch, search (including title + genre and title + author + genre combinations), copies, availability, archive, and the visibility PATCH. This was the guide example.
Member — 7 tests (PR #18): create, fetch by id, fetch by email.
Transaction — 10 tests (PR #19): borrow, return, get by id, borrower active/history, all-active, overdue.
Discovery — 2 tests (PR #20): the PUBLIC-copy discovery query.
Handler — 3 tests (PR #21): the last piece, today.
92 tests when the phase closed (48 → 92 in fifteen days).
Two lessons the tests taught me
1. A query parameter is part of the request.
The Member tests caught me out on this one. Three getMemberByEmail tests were failing — or worse, passing for the wrong reason — because they never sent the email parameter. Spring returns 400 before your service ever runs when a required parameter is missing, so the stub never fires and the test proves nothing about your code. The fix was one line per test — .param("email", ...) — and the 400 test needed no stub at all, just a verify(never()) that the service was never called. Lesson, now a rule for me: if a test asserts a 400, ask what produced it — the framework, or your code?
2. A route with no test has no proof it exists.
The Discovery controller shipped in PR #17 mapped to /api/v1/dicovery — missing the "s". It survived three merged PRs and 89 tests, because no test had ever called that URL. Reviews passed right around it. Then I wrote the empty-list test against the real /api/v1/discovery, and it was about to 404 — not because the test was wrong, but because the controller was spelled wrong. The fix was a single letter, and I'd already made it locally before anyone told me it would fail. It shipped with the Discovery tests in PR #20, and "dicovery" is gone from the codebase.
One handler for every error
The other half of Phase 2 is the part clients actually feel: GlobalExceptionHandler, a single @RestControllerAdvice that owns every failure, so all four controllers fail the same way. Every error body has the same shape:
public record ErrorResponse(
LocalDateTime timestamp, int status, String error, String message, String path) {
}
The families:
404 — not found: missing book, copy, borrower, borrowing, or member.
409 — conflict: duplicate book, copy, or member; already borrowed; unavailable copy; borrow limit exceeded.
400 — business rules: returning a book that was never borrowed, deleting a book with history, archiving a book with an active loan, an invalid copy state.
400 — validation: a bad request body returns the field→message map, so the client knows exactly which field failed and why.
400 — Spring's own errors: a type mismatch like GET /catalog/abc, a missing request parameter, an unreadable body — these used to fall into the 500 fallback. Now they land in their own handler:
@ExceptionHandler({
MethodArgumentTypeMismatchException.class,
MissingServletRequestParameterException.class,
HttpMessageNotReadableException.class
})
public ResponseEntity handleSpringBadRequest(
Exception ex, HttpServletRequest request) {
return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(new ErrorResponse(
LocalDateTime.now(),
HttpStatus.BAD_REQUEST.value(),
"Bad Request",
ex.getMessage(),
request.getRequestURI()));
}
500 — the fallback: anything unexpected returns a generic message and gets logged. Never an internal detail, never a stack trace leaking to a client.
The test rule that made the handler tests honest: test the handler through MockMvc, not by calling it directly. @WebMvcTest loads it automatically — you trigger each failure the way a client would and assert the error JSON. The 500 test stubs a plain RuntimeException from the mocked service and asserts the generic message. And a small trap from the earlier phases still applies: on a success body, $.status is the domain loan status, never the HTTP code — status().isXxx() owns the HTTP code.
What this means in practice
A missing book is a clean 404. A bad body is a structured 400 with field errors. A conflict is a 409, not a stack trace. The API is now something a client — and eventually a real member of this platform — can actually call and understand when it fails.
What this unlocks
I set myself a rule back in October: no freelancing profile updates, no new platforms, until the REST API was complete. That gate is now open. The project is no longer a library only other code can use; it's a platform members can actually call.
What's next
The next chapter isn't decided yet, and I'm not going to invent one for the end of this post. What I will say is what this phase taught me: the boring consistency work — one error shape, one response shape, one test per route — is what turns a collection of endpoints into an API.
If you've built controllers in Spring, what's the first thing you test — the happy path, or the error shape? And have you ever had a typo survive your reviews because nothing actually called the route?
Code, if you want to follow along or tell me what you'd do differently: github.com/Pekins1/LibraryManagementSystem
— Rahkel
Top comments (0)