System design / Lesson 1

Start with requirements

Turn a short-link service brief into concrete behavior, quality targets, and acceptance scenarios.

Start with a decision

“Design a URL shortener” leaves most important decisions open. Can someone edit a destination? Must a link stop working at noon? Can the service lose a link after saying it was created? A database diagram cannot answer those questions. Requirements give you a way to judge whether a design works.

This lesson proposes a small, illustrative service for a team that shares long documentation URLs. It is a design exercise, not a description of a deployed application. The first version creates a short link and redirects visitors. A creator may provide an expiry deadline. Accounts, analytics, custom aliases, editing, and revocation are outside this first scope.

Start with a concrete journey: someone submits a destination, receives a generated code, and shares it. Another person opens that code. At each step, ask what success means and which failures the person can observe.

Ask concrete questions

Functional requirements describe behavior. Quality requirements describe how well that behavior must work under stated conditions. “Redirect a valid code” is functional. “Keep redirect latency below a target at an agreed load” is a quality requirement. Both need a precise boundary.

Questions that change this design
AskDecision for this exercise
Who chooses the code?The service generates it and enforces uniqueness in storage.
Which destinations are accepted?Absolute HTTP or HTTPS URLs with a host; malformed input is rejected.
What does no deadline mean?The link has no business expiry.
What happens at the deadline?The link is expired, including exact equality.
Can a code change meaning?No edits or code reuse in this version.

A generated code still needs collision handling: a storage uniqueness constraint prevents two destinations sharing a code. An HTTP/HTTPS allowlist alone does not make a public shortener safe from abuse. A public launch would need a separate abuse and access policy; here, assume a controlled team service.

Write the contract

Use POST /links to create a link. Accept an optional future expires_at timestamp with an explicit timezone, normalize it to UTC, and reject invalid input with 400. The example response follows a successful persistent commit. Do not acknowledge creation merely because a cache accepted a write.

POST /links
Content-Type: application/json

{
  "url": "https://example.org/guide",
  "expires_at": "2026-12-01T12:00:00Z"
}

HTTP/1.1 201 Created
Content-Type: application/json

{"code":"k7m2q","short_url":"https://short.example/k7m2q"}

For GET /k7m2q, propose 302 Found with the destination in Location. The browser then makes a separate request to that destination. This temporary redirect choice applies to GET; method preservation for arbitrary requests is outside this contract. See RFC 9110, 302.

Return 404 for an unknown or expired code. If required storage is unavailable and there is no valid cached record, return 503. These are proposed service policies: a failed lookup is not evidence that a link is absent. The HTTP meanings are defined in 404 and 503.

The stored record contains the code, destination, and optional absolute deadline. Persistent storage is the source of truth. A cache is an optional copy. Its TTL answers “how long may this copy remain?” Business expiry answers “may this link redirect?” Database cleanup and cache eviction must not decide validity.

Set quality targets

Assume, hypothetically, 100,000 redirects and 10,000 creates per day. Dividing by 86,400 gives about 1.16 redirects and 0.12 creates per second on average. That says nothing about a shared link receiving thousands of visits together. Ask for peak rate, burst duration, destination size, retention period, and the cost of downtime before sizing infrastructure.

For discussion, choose a target of server-side redirect p95 below 100 milliseconds at an agreed test load: at least 95% of measured redirects should finish within that time. This is a target, not a tested result. Define measurement from handler entry to response completion; DNS, connection setup, and the destination page are separate. Report errors alongside latency so fast failures do not look healthy.

Begin with one service and persistent storage. Measure a representative workload before adding a cache, replicas, queues, or partitions. Reliability also needs an explicit promise: acknowledged records must survive a process restart; stronger host-failure recovery needs storage and backup decisions. A daily traffic estimate cannot supply those guarantees.

Acceptance scenarios

Turn decisions into examples a test can check. Freeze the clock rather than sleeping until a deadline.

  • Create: valid input returns a generated code only after commit; restarting the service preserves its mapping.
  • Redirect: a stored, unexpired code returns 302 and the exact stored destination.
  • Boundary: for deadline 2026-12-01T12:00:00Z, a validity check one instant before accepts it; a check exactly at or after rejects it with 404.
  • Outage: no usable cached record plus a failed database read returns 503, not 404.
  • Retention: evicting a cache entry does not expire a permanent link; a warm cache cannot extend an expired link.

The deadline applies when the service decides whether to redirect. Network delivery may happen later. The next system design lesson traces that decision through the request path. For a separate implementation case, read cache expiry versus link expiry.

Practice

1. Rewrite “the service must be fast” as a useful requirement.

Specify an operation, measurement boundary, percentile, workload, and target. For example: server-side GET redirect p95 below 100 ms at an agreed peak workload, with the error rate reported separately. Then validate it with a load test.

2. A five-minute cache entry disappears. Has its permanent link expired?

No. The copy was evicted. Read persistent storage and apply the record’s business deadline. An absent deadline still means no business expiry.

3. The database times out for a code you have never seen. Which response fits?

Under this proposed contract, 503. The service cannot establish whether the code exists. Return 404 only after a successful lookup establishes absence or expiry.