This chapter covers the URL Shortener API. We will look at every endpoint, how data flows, what we store, and the order in which we will build the project.
What Is a URL Shortener
A URL shortener takes a long URL like https://dalabs.academy/courses/test-driven-development-with-nodejs/getting-started/project-setup and maps it to a short code like abc123. Anyone who visits http://localhost:3000/abc123 gets redirected to the original URL.
Diagram showing how a long URL maps to a short code and redirects back
The behavior is easy to understand, but there is enough underlying complexity to make this a great project for learning test-driven development:
Multiple endpoints: We will build routes for creating, redirecting, listing, viewing stats, and deleting. Each one offers a clean TDD cycle.
Clear input/output contracts: Every endpoint has a well-defined request and response, making it easy to write assertions.
Incremental complexity: We start with a hardcoded response, move to in-memory storage, and eventually swap in a real database. Each step builds on the last, while our tests protect us from breaking things.
Delete a shortened URL. This endpoint returns no body.
DELETE /urls/abc123
→ 204 No Content
If the requested code does not exist, the server returns a 404.
Request Flows
Two main user flows drive this system.
Shorten Flow
A client sends a POST request to /shorten with a long URL.
The API generates a unique short code. This is a random string like abc123 that maps to the original URL.
The API stores the mapping of the short code to the original URL.
The API returns the short code and the full short URL.
Redirect Flow
A client visits http://localhost:3000/abc123.
The API looks up the short code abc123 in storage.
If the code is found, the API increments the click counter and responds with a 302 redirect to the original URL.
If the code is not found, the API returns a 404.
Architecture diagram showing the URL Shortener API with endpoints and database
Everything else in the application, like listing URLs, viewing stats, and deleting, is standard CRUD functionality built on top of this stored data.
What We Store
Every shortened URL requires four fields:
url: The original long URL.
shortCode: The generated short string (like abc123).
clicks: How many times the short URL has been visited. This usually starts at 0.
createdAt: The date and time the short URL was created.
It does not matter yet whether we store this data in a plain JavaScript object, a Map, or a database row. Conceptually, these four fields will power every endpoint.
How We'll Build It
We are not going to build everything at once. Each phase introduces a bit more complexity, and the tests we write along the way will keep us safe as we make changes.
Section 2: Building the Core (where we are now). We start with POST /shorten using a hardcoded response. We will write the test, return a hardcoded value to make it pass, and then replace that fake value with real logic. Next, we will add in-memory storage using a Map and extract a service layer. By the end of this section, we will be able to shorten URLs and generate unique codes entirely in memory, without a database.
Section 3: Adding a Real Database. We will spin up PostgreSQL with Docker, set up Prisma as our ORM, and swap out the in-memory Map for real database queries. Our existing tests will tell us immediately if this migration breaks anything.
Section 4: Expanding the API. We will build the remaining endpoints: redirecting with click tracking, listing all URLs, viewing stats, and deleting. Each endpoint follows the same TDD cycle.
Section 5: Hardening & Edge Cases. We will add URL validation, handle short code collisions using PostgreSQL advisory locks, and cover the edge cases that separate a simple demo from a production service.
Section 6: Testing Infrastructure. We will look at advanced test isolation, parallel test safety, and setting up a CI pipeline with GitHub Actions. This makes the test suite itself production-grade.
This progression is intentional. We fake the behavior first, make it real, and then make it robust. Each step is small enough that you always know exactly what changed and why. Because tests from previous chapters keep running, you will know immediately if something breaks.
In the next chapter, we will write our first test for POST /shorten, fake the response to make the test pass, and see this pattern in action.
