Back to path
BeginnerLinkly · Project 2 of 12 ~5h· 5 milestones

Design its core: API, data model, and short codes

Continues from the last build: a sized problem with no design.

Rung 1 left you with numbers on a page and nothing that runs: 200 writes/sec average, 100,000 redirects/sec at peak, and a 5-year storage target of 31.5 billion URLs, but not one endpoint, table, or short code exists yet.

REST API designRelational data modelingBase62 encodingDistributed ID generation basicsCollision handlingHTTP redirect semanticsWriting an ADRBack-of-envelope capacity math
Build this freeBrowse all projectsNo credit card. Already a member?

What you'll build

A working paper design: a versioned REST contract for create and redirect, a single-table schema with justified columns and indexes, ADR-001 choosing counter+base62 over hash or random codes with the keyspace math to defend it, a collision-safe short-code prototype, and ADR-002 choosing 302 over 301 and naming the deliberate MVP boundary that the next ten rungs will each chip away at.

See how we teach, before you sign up

You don't just get code dumped on you. Every starter file and every solution is explained line-by-line, in plain English. Here's one real file from this project:

starterKit/adr-template.mdmarkdown
# ADR-000: <Decision Title>

## Status
Proposed

## Context
What problem are we solving. What numbers from rung 1 apply here.

## Options Considered
1. Option A - tradeoffs
2. Option B - tradeoffs
3. Option C - tradeoffs

## Decision
The chosen option, one paragraph.

## Consequences
Positive and negative outcomes, what this makes easier, what it makes harder or defers to a later rung.

Reading this file

  • ## StatusEvery ADR starts life as Proposed and becomes Accepted once the team commits.
  • ## Options ConsideredList at least two real alternatives, not just the one you picked, or the ADR can't be defended later.
  • ## DecisionOne paragraph, no hedging: this is the sentence an interviewer will ask you to justify.
  • ## ConsequencesName what gets harder, not just what gets easier; every decision defers some cost to a later rung.
  • Positive and negative outcomes, what this makes easier, what it makes harder or defers to a later rung.This is the line that keeps the ladder honest: nothing is free, it's just deferred.

Copy this for both ADR-001 (code strategy) and ADR-002 (redirect semantics + MVP boundary).

That's 1 of 7 explained code blocks in this single project.

The build, milestone by milestone

  1. 1

    Define the API contract: create and redirect

    4 guided steps

    A URL shortener that can't state its own API in one page can't be scaled, rate-limited, or cached with any precision, because nobody agrees what a 'request' even is yet.

  2. 2

    Design the data model: one table, the right columns

    4 guided steps

    A schema designed before the API tends to grow columns nobody asked for; a schema designed after tends to be missing the one column the redirect path actually needs. Doing it in this order keeps the table minimal on purpose.

  3. 3

    Choose the short-code generation strategy

    4 guided steps

    This is the decision an interviewer is actually listening for in a URL-shortener question. Get the keyspace math wrong and the system either runs out of codes early or collides constantly; get it right and you can explain, in one paragraph, why collisions are structurally impossible for the common path.

  4. 4

    Handle collisions on the paths that can still have them

    4 guided steps

    Interviewers probe this because 'my ID can't collide' is only true for the generated path; the moment a product adds custom aliases (a very common real feature), collision handling becomes mandatory again, and a design that forgot this looks unfinished.

  5. 5

    Decide the redirect status code and write the closing ADR

    4 guided steps

    301 vs 302 looks like trivia but it decides whether clicks are observable at all: a cached 301 means the browser stops calling your API, which silently breaks click counting (rung 8) and any future long_url edit.

What's inside when you start

3 starter files, ready to clone
5 guided milestones
4 full reference solutions
7 code blocks explained line-by-line
5 "is it working?" checks
4 interview questions it prepares you for

You'll walk away with

A written REST API contract for POST /api/v1/urls and GET /{code}, including every status code
A single urls table data model with every column justified against the API contract
ADR-001: counter+base62 vs hash vs random short codes, with a keyspace table and fill-ratio math
A working short-code generator prototype (base62 encode/decode plus a collision-safe retry path)
ADR-002: 301 vs 302 for redirects, plus an explicit MVP system boundary section

This is portfolio-grade. Build it free.

Sign up to unlock every milestone step-by-step, the code skeletons, full reference solutions, and checkable tasks, with your progress saved as you build.

Start building