URL Stats (GET /urls/:code/stats)

ISO-8601. The standard, sortable, timezone-explicit date-string format, like "2026-06-14T09:31:12.345Z". We serialize createdAt this way so the timestamp is deterministic on the wire instead of depending on locale or client parsing.

Response schema. A declared output shape that Fastify enforces, so the JSON can't silently drift — a field can't change type or go missing without a test catching it. It turns "it happens to return these fields" into "it is guaranteed to return exactly these fields."

404 for unknown. A missing code is a clean not-found, not an empty 200 body. The handler asks the store for the record and, on undefined, returns 404 { error, message } — the same miss contract the redirect route already uses.

Why a Locked, Schema-Backed Stats Endpoint

A list view answers "what URLs exist?" but not "tell me everything about this one." The stats endpoint fills that gap — and the two details that shape its response are exactly what separate a sloppy endpoint from a trustworthy one. Serialize createdAt however the runtime feels like, and the date format drifts with locale; skip the response schema, and a refactor can quietly drop a field or flip its type with no test to catch it. Locking both means the body is the same every time, on every backend, and the 404 keeps the contract honest: an unknown code is a deliberate not-found, never a half-empty success.

A Second Read Method on the Seam

We already have two read methods on the UrlStore seam. findByCode returns just the original URL string — that's all the redirect route ever needed. list returns a page of records. Neither fits the stats endpoint: it needs the whole record for one specific code, not a string and not a page.

So we add a third read method rather than overloading an existing one:

findRecordByCode returns the same UrlRecord shape that list already surfaces — { shortCode, originalUrl, clicks, createdAt } — or undefined when the code is unknown, mirroring findByCode's miss contract. We could have widened findByCode to return the record, but that would force the redirect route — which only wants a string — to carry a richer type it never uses. A narrow method per need keeps each caller honest about what it actually reads.

The teaching beat here is what didn't change. The in-memory store has tracked the full UrlRecord (including createdAt and clicks) in a single Map since chapter 15, so the seam was already consistent. Adding the method to the in-memory store is one line:

No record-shape change, no new field, no migration — the data was already there. We're just exposing it through a new accessor.

The Prisma store projects the row to the same UrlRecord shape, dropping the internal id and normalising a miss the way every other read method does:

findUnique returns null on a miss; we normalise that to undefined so both backends honour the same contract — the route's behaviour is identical whichever store it talks to. The projection drops id: it's an internal serial primary key, never part of the public stats shape, so it stops at the repository boundary.

The Response Schema and Date Serialization

The stats body has five fields, and we lock all of them with a Fastify response schema:

Two of these deserve a closer look. createdAt is a JavaScript Date in both stores, but the schema types it as a string — so the handler serializes it explicitly with record.createdAt.toISOString() before returning. Fastify's JSON serializer would turn a Date into the same ISO string anyway, but the explicit call makes the contract obvious in the code and lets the string-typed schema validate the output cleanly — identical whether the record came from the in-memory Map or Postgres.

shortUrl is derived — it isn't stored anywhere. We build it from shortCode in the handler so the client gets a ready-to-use link without reassembling it. This mirrors the list endpoint from chapter 15, keeping the two endpoints' item shapes consistent.

Route Ordering

Chapter 15 had to fight the /:code catch-all: GET /urls looks like a redirect for the code "urls" unless the list route is registered first. The stats route doesn't have that problem. /urls/:code/stats has a static /urls prefix and a three-segment shape, so Fastify's radix router never confuses it with the bare one-segment /:code catch-all or the two-segment-free /urls list.

Even so, we register it before the catch-all alongside listRoute — consistent placement, no surprises:

We don't just trust the router — a unit test asserts GET /urls/abc123/stats returns the stats object (200, no Location header, data is not an array), proving it's served by the stats route and not swallowed by the redirect or list.

Step 1: The Failing Tests (Red)

Check out the start branch, install, and bring up the database:

The start branch ships the tests first and no implementation. The Docker-free unit suite injects the in-memory UrlService and covers five cases against GET /urls/:code/stats: the happy-path 200 with the full body, the ISO-8601 createdAt serialization, the click count reflected in the response, the 404 for an unknown code, and the route-ordering proof.

The ISO test is a neat round-trip assertion: createdAt === new Date(createdAt).toISOString() only holds if the string is already a canonical ISO-8601 value — re-parsing and re-serializing it produces the exact same string. If the handler returned a raw Date (or any non-ISO format), the comparison would fail.

The integration suite mirrors the happy path and the click count against the real database, wiring PrismaUrlRepository.

The click-count case is end-to-end through Postgres: shorten a URL, hit /:code three times so the redirect route's atomic increment runs, then read the stats and assert clicks: 3 — the same counter the redirect bumps, surfaced through the new endpoint.

Run both suites:

There's a nuance worth catching in the red. With no stats route registered, GET /urls/abc123/stats is a three-segment path that matches nothing — not even the /:code catch-all, which is a single segment — so Fastify returns its own 404. That means the unknown-code 404 test passes on the start branch: a missing endpoint and a missing code both produce a 404. The happy-path cases are what fail — they expect 200 and get 404. The red is purely behavioural.

Step 2: Add findRecordByCode and the Route (Green)

Switch to the finish branch:

The finish branch adds findRecordByCode to the UrlStore interface and both stores (shown above), plus the new route. The handler is thin: read the validated code, ask the store for the record, and branch.

The handler never touches a database directly — it talks only to urlStore.findRecordByCode, so the same code runs against the in-memory store in the unit tests and Prisma in integration and production. An undefined record becomes a 404 { error, message }, reusing the same shape the redirect route returns for a missing code. A found record is projected to the response body, with createdAt.toISOString() doing the date serialization the schema's string type expects.

With the route registered before the catch-all in app.ts, /urls/:code/stats resolves to the stats handler.

Step 3: Green on Both Suites

Run everything:

Green on both. The unit suite proves the stats logic and the ISO serialization Docker-free; the integration suite proves the same body lands from a real Postgres row.

When you're done, stop the container:

The Scope Boundary: Richer Stats Later

The stats we return — clicks and createdAt — are everything already sitting on the urls row. That's deliberate, and it's worth naming what we didn't build. A real analytics view would want lastAccessedAt, the top referrers, the user-agents, or a per-day click breakdown. None of those can come from a single counter column.

A clicks integer can only ever answer "how many?" — it can't answer "when?" or "from where?". Those questions need a separate, append-only click-events table: one row per hit, recording the timestamp, referrer, and user-agent, that the stats endpoint then aggregates. That's a fundamentally different data model — high write volume, queried by time range — and it's exactly the workload the table-partitioning bonus chapter (chapter 24) tackles, partitioning the events table by created_at range so per-day rollups stay fast at scale. So this isn't an omission; it's a scope boundary we'll cross deliberately once the data model is ready for it.

What's Next

The full read side of the API is in place. Next we close the loop with delete (DELETE /urls/:code) — a 204 on success, the idempotency question, and a test that proves the row is actually gone.