Design: a URL shortener on one machine

The prompt

"Design a URL shortener." It's the most common opening question because it's small enough to finish in an interview and still has real decisions in it: how codes are made, how redirects stay fast, where clicks are counted, and what happens when the machine fails. This version stays at Snip's launch scale; 15.02 Design: a URL shortener at scale takes it to a hundred times that.

1. Requirements

Functional

• Create a short link for a long URL, optionally with a custom alias (snip.example/spring-sale) and an expiry date.
• Redirect anyone who opens the short link.
• Show the owner a click count per link.

Non-functional

• Redirects under 50 ms at the server for 99% of requests, available 99.99% of the time.
• A link, once created, is never lost.
• Codes can't be guessed or enumerated: some links point at private documents.
• Click counts can lag by a few seconds.

Out of scope: user accounts beyond an API key, detailed analytics, editing a link's destination.

2. Estimates

From 01.05 Back-of-the-envelope estimation: 10 million links a month is about 4 writes a second on average and 10 at peak; with 100 redirects per link, about 350 reads a second and 1,000 at peak; and 600 million links of 500 bytes each over five years is 300 GB.

What it decides: one ordinary Postgres server handles this with room to spare. The design doesn't need sharding, a queue or a cache cluster. It does need a second copy of the data, because 99.99% is about 4 minutes of downtime a month (14.02 SLOs and error budgets), and one machine can't promise that on its own.

3. Entities and API

Link   { code (primary key), long_url, owner_id, created_at, expires_at? }
Clicks { code, day, count }

POST /links        { long_url, alias?, expires_at? }   Idempotency-Key: …   →  201 { code, short_url }
GET  /{code}                                                                 →  302 Location: long_url
GET  /links/{code}/stats                                                     →  200 { clicks, by_day }

The create call takes an idempotency key (03.10 Idempotency keys) so a retried request doesn't make a second link. The redirect answers 302, not 301: a 301 is cached by browsers, so later clicks never reach Snip and are never counted, and the destination can never change (01.06 Trade-offs: there is no best design).

4. High-level design

5. Deep dives

import { randomInt } from "node:crypto";

const ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";

export function randomCode(length = 7) {
  let code = "";
  for (let i = 0; i < length; i++) code += ALPHABET[randomInt(62)]; // randomInt avoids modulo bias
  return code;
}

export async function createLink(db: pg.Pool, longUrl: string, ownerId: number, draw = randomCode) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const { rows } = await db.query(
      `INSERT INTO links (code, long_url, owner_id) VALUES ($1, $2, $3)
       ON CONFLICT (code) DO NOTHING RETURNING code`,
      [draw(), longUrl, ownerId],
    );
    if (rows.length) return rows[0].code as string; // no row back: the code was taken, draw again
  }
  throw new Error("no free code after 5 attempts");
}

Tested on Postgres 16: 10,000 links were created in about 0.7 seconds on one connection. With the first draw forced to an existing code, the insert returned no row and the second draw succeeded; with every draw forced to a taken code, the function gave up after five attempts instead of looping forever. The redirect's lookup by code used the primary key index.

Expiry and aliases. An expired link is checked on read (expires_at < now() answers 404) and deleted later by a nightly job, so expiry never needs a timer per link. Aliases need a reserved list (api, login, admin) and the same character rules as codes.

6. Wrap-up: what breaks first

• The machine. The standby is promoted when the primary fails, by a tool like Patroni or a managed database's failover, in about a minute (04.07 Replication: leaders, followers and lag). That's most of a month's 99.99% budget, which is why the next step is two app servers behind a load balancer (02.03 Stateless servers behind a load balancer).
• Growth. At a hundred times the traffic, 30 TB and 100,000 redirects a second don't fit on one machine. That's 15.02 Design: a URL shortener at scale.

Recap

Interview questions