System Design: [URL shortener name]

Reference design for a URL shortening service that turns long URLs into short codes and redirects visitors at high volume and low latency. It covers capacity estimation, the public API, key generation (base62 encoding, counters, hashes and pre-generated keys, collision handling), the data model, the 301 versus 302 redirect trade-off under RFC 9110, caching, the click analytics pipeline, abuse and malicious URL protection, custom aliases, expiry and multi-region deployment. It follows the structure of the System Design Document template and is pre-filled with a worked design to adapt. Values marked Example are assumptions. Replace every [bracketed] value and every row marked Example.

Document control

Approvals

Revision history

Contents

1. Overview
2. Requirements
3. Capacity estimation
4. API design
5. Data model
6. High-level design
7. Detailed design
8. Scalability and performance
9. Reliability, security and operations
10. Trade-offs and alternatives
11. Delivery plan and risks
12. Appendices

1. Overview

1.1 Problem statement

[Example: Product teams embed long tracking URLs in SMS, printed material and social posts. Long URLs break in some clients, cannot be updated after printing and give no click data. Teams currently use three external shorteners with different terms, no central takedown process and no data residency control.]

1.2 Proposed solution

[Example: A first-party shortener on a dedicated short domain. Clients create links through an authenticated API; the service assigns a 7-character base62 code from a pre-allocated counter range, passes the destination through a keyed permutation so codes are not sequential, checks the destination against URL reputation feeds and stores the mapping in a replicated key-value store. Visitors hit a stateless redirect tier that serves most lookups from an in-memory cache and answers with HTTP 302. Each redirect emits a click event to a message queue; a stream job aggregates clicks for the statistics API. Links can expire, be disabled by trust and safety, or carry a custom alias.]

1.3 Decisions requested from reviewers

2. Requirements

2.1 Functional requirements

2.2 Non-functional requirements

2.3 Out of scope

• [Example: link-in-bio pages and landing page builders]
• [Example: QR code rendering (handled by the client libraries)]
• [Example: user-level tracking across links; analytics are aggregate only]
• [Item deferred, with the release that will take it]

3. Capacity estimation

3.1 Assumptions

3.2 Request rates

A 30-day month has 2 592 000 seconds:

Per day that is about 3.33 million creates and 333 million redirects.

3.3 Storage and key space

Base62 key space for code length $\ell$ is $62^{\ell}$:

Six characters would be 10.6% full after five years, which makes random codes collide often and leaves little room for growth. Seven characters are $(6 \times 10^{9}) / (3.52 \times 10^{12}) \approx 0.17\%$ full after five years.

3.4 Cache and analytics

Caching the hot 20% of a day's redirects as an upper bound:

Click events:

3.5 Summary

4. API design

4.1 Endpoints

4.2 Request and response examples

Create a link, then follow it from the short domain:

POST /v1/links HTTP/1.1
Authorization: Bearer [token]
Idempotency-Key: 6f1c2a9e-4b7d-4c1e-9a55-0d3f2b8e7c11
Content-Type: application/json

{"url": "https://www.example.com/spring-sale?utm_source=sms&utm_campaign=s26", "alias": null, "expires_at": "2027-03-31T23:59:59Z", "redirect": 302}

HTTP/1.1 201 Created
Location: https://api.sho.rt/v1/links/k7Qx2Lm
Content-Type: application/json

{"code": "k7Qx2Lm", "short_url": "https://sho.rt/k7Qx2Lm", "url": "https://www.example.com/spring-sale?utm_source=sms&utm_campaign=s26", "redirect": 302, "expires_at": "2027-03-31T23:59:59Z", "status": "active"}

GET /k7Qx2Lm HTTP/1.1
Host: sho.rt

HTTP/1.1 302 Found
Location: https://www.example.com/spring-sale?utm_source=sms&utm_campaign=s26
Cache-Control: private, max-age=60
Referrer-Policy: strict-origin-when-cross-origin

4.3 Errors and idempotency

A retried POST with the same Idempotency-Key and body within 24 hours returns the original response; with a different body it returns 422. Keys are stored with the owner ID so two owners cannot collide.

5. Data model

5.1 Entities

Links are the core record; click aggregates and abuse reports hang off the code.

5.2 Storage choices

The link record is immutable except for status, expires_at and, for 302 links, long_url. Every change is written to an audit table with the actor.

6. High-level design

7. Detailed design

7.1 Key generation

Base62 uses the alphabet 0-9a-zA-Z (digits are values 0 to 9, lower case 10 to 35, upper case 36 to 61). Encoding repeatedly divides the number by 62 and maps remainders to characters, most significant first. For example $125 = 2 \times 62 + 1$ encodes as 21, and $11\,157 = 2 \times 62^{2} + 55 \times 62 + 59$ encodes as 2TX.

Chosen: counter ranges (blocks of 1 000 000 IDs) with a keyed bijective permutation of the ID space $[0, 62^{7})$ before encoding, for example a format-preserving encryption mode such as FF1 from NIST SP 800-38G. The permutation makes codes look random while preserving uniqueness; it is an obfuscation against casual enumeration, not access control, so private destinations still need authentication at the destination.

At the peak create rate of 193/s, one block lasts at least $10^{6} / 193 \approx 5\,181$ s (about 86 minutes) even if a single instance served all creates. Losing an unused block wastes IDs, not correctness: the key space is 0.17% used after five years.

Collision handling: every write is a conditional insert ("put if absent") on code. With counter ranges a conflict indicates a bug or an alias clash, so the API raises an alert and allocates the next ID. With random or hashed codes the expected retries per insert are about the occupancy ratio, so 0.17% at five years. The birthday bound shows why the check is mandatory rather than optional: for $n$ random codes in a space of size $M$, the chance of at least one collision is about $1 - e^{-n^{2}/(2M)}$, which is effectively 1 for $n = 6 \times 10^{9}$ and $M = 3.52 \times 10^{12}$.

7.2 Create flow

Normalisation lower-cases the scheme and host and removes default ports; it never rewrites the path or query, because those are meaningful to the destination. Dedupe (Q-03) is per owner and off by default, since two campaigns often need separate statistics for the same URL.

7.3 Redirects: 301 versus 302

RFC 9110 defines 301 (Moved Permanently, section 15.4.2) and 308 (Permanent Redirect, 15.4.9) as permanent and lists them among the status codes that are heuristically cacheable; 302 (Found, 15.4.3) and 307 (Temporary Redirect, 15.4.8) are temporary. 307 and 308 require the client to keep the request method; for a shortener visitors almost always send GET, so the difference matters little.

Chosen: 302 by default with Cache-Control: private, max-age=60, so NFR-06 (takedown within 60 s) holds and analytics stay complete. Owners can opt into 301 for links they declare permanent and will never edit; such links cannot change destination, and takedown relies on the warning page reaching visitors whose browsers have not cached the redirect.

7.4 Caching

• Redirect tier cache: read-through cache keyed by code with TTL 60 s for active links. Status changes publish an invalidation event so blocked links leave every regional cache within seconds, with the TTL as the backstop.
• Negative caching: unknown codes are cached for 30 s to absorb scanning bots without hitting the store.
• Edge caching: when enabled, the redirect carries Cache-Control: max-age=60 instead of private (a private response must not be stored by a shared cache), so the CDN may cache 302 responses for the same 60 s, which cuts origin load during campaign spikes. Click counting then happens from edge logs for cached hits, or edge caching is disabled for links with analytics enabled; choose one and record it in 12.1.
• Hit ratio: with a 90% cache hit ratio the store serves about $19\,290 \times 0.1 \approx 1\,929$ reads/s at peak.

7.5 Analytics pipeline

The redirect service writes a click event to a local buffer and returns the redirect; a background sender publishes batches to the click event queue (see Message queue design (system-design/design-message-queue)). Losing a few events during a crash is accepted: analytics are at-least-once from the queue onwards and best effort before it.

Privacy: no cookies are set on the short domain; IP addresses are truncated before storage and never exposed through the API; aggregates below 10 clicks per bucket are shown as "fewer than 10" to limit re-identification.

7.6 Abuse and malicious URL protection

A blocked link returns a warning page that does not render the destination as a clickable link. Repeat offenders have all their links disabled.

7.7 Custom aliases

• Allowed characters [A-Za-z0-9_-], length 4 to 30 (Example); case is significant, matching generated codes.
• A reserved list blocks paths used by the service (api, login, help), brand names and offensive words.
• Aliases share the code key space and use the same conditional insert, so an alias can never shadow a generated code.
• Short aliases (4 to 6 characters) are limited to paid plans to reduce squatting.

7.8 Expiry and deletion

Expiry is checked at read time (expires_at or click limit reached) and the service returns 410. A daily job marks expired links and removes them from caches. Codes are never reused: a reused code would send old printed or bookmarked links to a new destination, which is both a safety and a fraud risk. Deleting a link removes the destination after 30 days but keeps the code tombstoned.

7.9 Multi-region

• Reads: each region has a redirect tier, cache and a full replica of the link store; redirects never leave the region.
• Writes: creates are accepted in any region. Counter blocks are allocated per region from disjoint ranges, so regions never collide on generated codes. Aliases use a conditional insert in a strongly consistent global table, accepting higher create latency for aliases only.
• Replication lag: a link created in region A and opened in region B before replication finishes would miss. On a local miss the redirect service asks the home region encoded in the code's block metadata before returning 404, and caches the result.

8. Scalability and performance

Latency budget for a redirect (target p99 20 ms at the service):

9. Reliability, security and operations

9.1 Failure modes

9.2 Security and abuse

Record these in the threat model (security/threat-model).

9.3 Observability

9.4 Cost estimate

10. Trade-offs and alternatives

11. Delivery plan and risks

11.1 Milestones

11.2 Rollout and rollback

[Example: Launch with internal teams only, then allow external accounts by plan tier. Migrated links from external shorteners are imported with their original codes on a separate path prefix and verified one by one before the old shortener's domain is pointed at the new service.]

11.3 Risks

12. Appendices

12.1 Open questions

12.2 Glossary

12.3 References

Standard and licence note

Based on common industry practice for URL shortening services and on the HTTP specifications cited in 12.3. This is a reference design to adapt, with illustrative numbers. Original text written for this collection; no text from the cited specifications is reproduced. Check the current versions of the RFCs and the terms of any reputation service before use. Template licence: MIT.