Delete a URL (DELETE /urls/:code)

204 vs 404. A 204 No Content status means success, but there is no data to send back. We removed the row, so the response body is empty. A 404 Not Found means there was nothing there to delete. We will return a 404 for a missing code.

Soft vs hard delete. A soft delete keeps the database row but flips a deletedAt flag. A hard delete physically removes the row using DELETE FROM urls. We will use a hard delete. This means there is no leftover data to filter out during future database reads.

Why a Boolean Seam and a Hard Delete

Deleting a record sounds simple, but it requires two specific design choices.

First, how does the handler know what status code to return? If you look the code up and then delete it, you make two trips to the database. This creates a race condition if the row changes in between. Instead, our delete method will return a simple boolean: did I remove a row? This collapses the check and the deletion into one safe operation. That boolean is all the handler needs to choose between a 204 and a 404.

Second, what does "delete" actually mean? If you hard-delete, the row is gone and all your existing read queries continue to work perfectly. If you soft-delete, the history survives, but every single query in your app must now filter out dead rows. If you forget one filter, you have a bug. We use a boolean return and a hard delete because they keep the code simple and consistent.

A delete Method on the Seam

Every endpoint so far has gone through the UrlStore interface we built in chapter 6. Delete is no different. We will add one new method:

The return type is the most important detail here. The delete method returns a Promise<boolean>. A true result means a row was removed, and false means there was nothing to remove. We do not call findByCode first to check if the record exists. The delete operation itself reports whether it found a match.

The in-memory store gets this behavior almost for free. JavaScript's Map.delete already returns a boolean telling you whether the key was present:

This takes just one line. Map.prototype.delete returns true if the key existed and was removed, and false otherwise. This perfectly matches the contract our interface promises.

Prisma: deleteMany over delete

The Prisma store requires a bit more thought. Prisma gives you two ways to delete a row, and the choice matters:

The obvious method is prisma.url.delete({ where: { shortCode } }). However, this method throws a P2025 error if no row matches. To use it, you would have to wrap the call in a try/catch block, look for that specific error code, and translate it into a false. Using exceptions for normal control flow—like a missing code—makes the code harder to read.

deleteMany never throws an error on a miss. Instead, it returns an object with a count property showing the number of rows removed. Because shortCode is marked as @unique in our schema, that count will only ever be 0 or 1. We can safely check if count > 0 to get the boolean our interface wants. There are no try/catch blocks and no error codes to match.

The Idempotency Decision: 404 for a Missing Code

We mentioned an open question earlier. Deleting an existing code returns a 204. But what should happen if you try to delete a missing or already-deleted code? There are two valid approaches.

• Idempotent 204. The final state is always "this code no longer exists", whether a row was actually removed or not. Under this logic, every delete call for a specific code could return a 204. This is a good choice if clients retry requests blindly and you want every retry to look successful.
• Informative 404 (what we chose). A 404 tells the caller the resource was not there to delete. This provides useful feedback if a user double-clicks a button or types the wrong code. An idempotent 204 hides this information, making it impossible for the caller to tell a real deletion from a non-action.

We chose the 404 for two reasons. First, it is informative. The response clearly distinguishes between "I removed it" and "there was nothing to remove". Second, it is consistent with the rest of the API. The redirect and stats endpoints already return a 404 for an unknown code. Making DELETE behave the same way keeps a uniform rule across every route: an unknown code always results in a 404.

The route handler encodes this decision directly:

The response schema declares both outcomes. 204: { type: "null" } documents the empty-body success. The 404 shape reuses the same { error, message } body that our other endpoints return. The handler calls urlStore.delete(code). A false result becomes a 404, while a true result triggers reply.code(204); return null. Because a 204 carries no body, returning null is the correct behavior.

Hard Delete vs Soft Delete

We chose a hard delete for this project. Here is the trade-off behind that choice.

• Hard delete (chosen). This is the simplest approach. The row is physically removed from the database. Every existing read operation—redirect, list, stats—continues to work without modification. There is nothing to filter because the data is gone. The downside is that you lose history. The click count and creation time vanish with the row.
• Soft delete (the alternative). You add a deletedAt timestamp column and update it instead of removing the row. History survives, which is useful for audit trails or preserving historical stats. However, the complexity spreads everywhere. Every read query must now include a WHERE deletedAt IS NULL filter. If you forget that filter on even one query, deleted URLs will leak back into your results.

As a general rule, choose a soft delete when you genuinely need the history and are willing to add filters to every read query. Choose a hard delete when simplicity is more important and losing the row's history is acceptable. For our URL shortener, a deleted link is meant to be gone. A hard delete is the right default, and it means we do not have to write a database migration to alter the urls table.

Route Registration

DELETE /urls/:code shares a similar path shape with the redirect's /:code catch-all. Fortunately, there is no collision. DELETE is a distinct HTTP method, so Fastify routes it completely separately from the GET requests. We register it alongside the other URL routes in app.ts:

Step 1: The Failing Tests (Red)

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

The start branch includes the tests but no implementation. The unit suite uses the in-memory UrlService and covers five cases: a successful 204 with an empty body, proof that reading a deleted code returns a 404, a 404 for a code that never existed, a 404 for an already-deleted code, and proof that a delete only touches the targeted code.

The second test case is the most important. It does not stop at checking the 204 status. It deletes the code, then tries to read it through two other endpoints to ensure both return a 404. If our code returned the right status but left the row behind, this test would catch the mistake. It proves the code is actually gone.

The already-deleted case tests our idempotency decision. It deletes twice0, expects a 204, deletes it again, and expects a 404. The second delete sees no row to remove, so the boolean is false and the handler returns the informative 404.

The integration suite tests the happy path against the real database using the PrismaUrlRepository. It confirms the deletion in the strongest way possible:

This is a critical assertion. It does not trust the 204 response. Instead, it queries the database directly with prisma.url.findUnique and asserts that the result is null. The status code claims the record was deleted, but findUnique proves it. Always confirm the actual effect, not just the HTTP response.

The third integration case is the mirror image. It deletes an unknown code, expects a 404, then queries an untouched row (keep01) to assert it is still there. This proves the delete operation did not accidentally remove the wrong data.

Run both suites:

There is a small nuance worth noticing in the test output. Because we have not registered the delete route yet, DELETE /urls/missing matches no handler. Fastify automatically returns a 404 for missing routes. This means the two unknown-code test cases actually pass on the start branch. The cases that fail are the ones expecting a real deletion.

Step 2: Add delete and the Route (Green)

Switch to the finish branch:

The finish branch adds the delete method to the UrlStore interface and both store implementations. It also includes the new deleteRoute, registered in app.ts. The handler is very thin. It reads the validated code, asks the store to delete it, and maps the boolean result to a status code. There is no second database lookup and no error handling around the Prisma call, because deleteMany cleanly provides the boolean we need.

Step 3: Green on Both Suites

Run everything:

Both suites now pass. The unit suite proves the boolean-to-status mapping works without Docker. The integration suite re-queries Postgres to prove the row is actually gone.

When you're done, stop the container:

What's Next

The API surface is now complete. We have built five endpoints, all fully test-driven. Next, we will add centralized error handling. We will create custom error classes and a single setErrorHandler that maps errors to a consistent response body without leaking sensitive stack traces.