Design a URL Shortener with React, .NET, SQL Server
On this page
Learning Objective
Design a URL shortener end to end, choosing an ID scheme that avoids collisions and enumeration, serving redirects at high read rates with caching, recording analytics without slowing redirects, and defending against abuse including malicious targets, open redirects and unsafe URL schemes.
Concept Explanation
A URL shortener looks trivial, a table mapping a short code to a long URL, and it is a classic design exercise because its interesting problems are hidden in the details. Requirements: users create short links, optionally with a custom alias and an expiry date, anyone visiting a short link is redirected quickly, and owners can see click analytics and delete links. Non-functional: redirects must be fast, at a few milliseconds of server time, and highly available since the link is embedded in places you cannot change, and creation is comparatively rare. That asymmetry, roughly a hundred reads for every write, shapes the whole design: optimize the redirect path ruthlessly and treat creation and analytics as secondary.
Estimate the scale. Suppose 100 million new links per month: that is about 40 creations per second on average. With a 100 to 1 read ratio, redirects run at about 4,000 per second on average and perhaps 40,000 at peak. Each row, with the code, target URL up to about 2 kilobytes, owner, timestamps, and flags, is around half a kilobyte, so a month of links is about 50 gigabytes, and years of retention reach tens of terabytes. Four thousand reads per second is trivial for a cache, and the write load is trivial for a database, so the design is dominated by the read path and by storage growth over time, not by throughput.
Generating the short code has three common approaches. Hashing the URL and truncating risks collisions and makes the same URL always produce the same code, which is wrong when different owners want separate analytics. A counter encoded in base 62, using digits and upper and lowercase letters, gives compact unique codes without collisions, and seven characters cover about 3.5 trillion values, but sequential codes are trivially enumerable: an attacker can walk through every link, including private ones. The fix is to keep a unique sequence in the database and scramble it with a reversible permutation, such as a format-preserving Feistel cipher keyed with a secret, before encoding, so codes look random yet never collide. A third option is random codes with a uniqueness check and retry, simple and unguessable at the cost of a lookup on creation. Custom aliases need a reserved-word list, since a user should not be able to claim admin, api, or a path your application uses.
The redirect path should touch as little as possible: look the code up in a cache such as HybridCache backed by Redis, on a miss read one row by primary key from SQL Server, populate the cache, and return an HTTP redirect. Choose the status code deliberately. A 301 permanent redirect is cached by browsers and intermediaries indefinitely, which reduces load but means later deletion or edits do not take effect for users who already followed it, and analytics undercount. A 302 or 307 temporary redirect is not cached in that way, so you keep control and can count each click, which is usually the right trade for a product with analytics and revocation. Record clicks asynchronously by writing an event to a queue or an in-memory channel and aggregating in the background, so a slow analytics store never slows a redirect.
A shortener is also an abuse magnet, so security is central. Attackers use them to hide phishing and malware links, so validate targets: allow only http and https schemes, reject javascript, data, and file, reject targets that point to private or loopback addresses, and check against a safe browsing or reputation service both at creation and periodically, since a benign page can turn malicious later. Rate limit creation per user and per address, require authentication for custom aliases, and provide an abuse reporting and takedown path that also invalidates the cache. Show an interstitial warning page for links flagged as risky. Never let the shortener itself become an open redirector to arbitrary parameters on your own domain, and keep the management API, with its ownership checks and rowversion, separate from the public redirect endpoint.
| Decision | Choice | Reason |
|---|---|---|
| Code generation | Sequence scrambled with a keyed permutation, base 62 | Unique, compact, not enumerable |
| Redirect status | 302 or 307 | Keeps revocation and analytics accurate |
| Read path | HybridCache with Redis, then primary key lookup | Thousands of reads per second at low latency |
| Analytics | Asynchronous events aggregated in the background | Never slows a redirect |
| Custom aliases | Reserved words, authentication, uniqueness constraint | Prevents route collisions and squatting |
| Abuse defense | Scheme allowlist, target checks, reputation, takedown | Shorteners are prime phishing tools |
Worked Example: Schema, Code Generation, Creation and Redirect Endpoints
The listings show the data model, a keyed base-62 encoder, the creation endpoint with URL validation, and the redirect endpoint with caching and asynchronous click recording.
CREATE SEQUENCE dbo.LinkSeq AS BIGINT START WITH 1 INCREMENT BY 1 CACHE 1000;
CREATE TABLE dbo.Links (
Code VARCHAR(16) NOT NULL CONSTRAINT PK_Links PRIMARY KEY, -- clustered on the lookup key
TargetUrl NVARCHAR(2048) NOT NULL,
OwnerId UNIQUEIDENTIFIER NOT NULL,
CreatedAt DATETIMEOFFSET NOT NULL CONSTRAINT DF_Links_Created DEFAULT SYSUTCDATETIME(),
ExpiresAt DATETIMEOFFSET NULL,
IsDisabled BIT NOT NULL CONSTRAINT DF_Links_Disabled DEFAULT 0, -- takedown switch
RowVer ROWVERSION NOT NULL
);
CREATE INDEX IX_Links_Owner ON dbo.Links (OwnerId, CreatedAt DESC) INCLUDE (Code, TargetUrl);
CREATE TABLE dbo.ClickDaily ( -- aggregated, not one row per click
Code VARCHAR(16) NOT NULL, Day DATE NOT NULL, Clicks INT NOT NULL,
CONSTRAINT PK_ClickDaily PRIMARY KEY (Code, Day)
);public static class CodeGenerator
{
private const string Alphabet = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
// Scramble the sequence with a keyed Feistel permutation (a bijection, so no collisions), then base62 it.
public static string FromSequence(long n, byte[] key)
{
ulong v = Permute((ulong)n, key); // reversible for a 42-bit domain, unguessable without the key
Span<char> buf = stackalloc char[8]; int i = buf.Length;
do { buf[--i] = Alphabet[(int)(v % 62)]; v /= 62; } while (v > 0);
return new string(buf[i..]);
}
private static ulong Permute(ulong x, byte[] key)
{
const int half = 21; const ulong mask = (1UL << half) - 1;
ulong l = (x >> half) & mask, r = x & mask;
for (var round = 0; round < 4; round++)
{
var f = RoundFunction(r, key, round) & mask;
(l, r) = (r, l ^ f);
}
return (l << half) | r;
}
private static ulong RoundFunction(ulong r, byte[] key, int round)
{
Span<byte> input = stackalloc byte[9]; BitConverter.TryWriteBytes(input, r); input[8] = (byte)round;
return BitConverter.ToUInt64(HMACSHA256.HashData(key, input));
}
private static readonly HashSet<string> Reserved = new(StringComparer.OrdinalIgnoreCase)
{ "api", "admin", "login", "logout", "health", "static", "assets", "bff", "hubs", "openapi", "www" };
public static bool IsAllowedAlias(string alias) =>
Regex.IsMatch(alias, "^[A-Za-z0-9_-]{4,32}$") && !Reserved.Contains(alias);
}// Creation: authenticated, rate limited, and the target is validated as hostile input.
public sealed class TargetUrlValidator(IUrlReputation reputation)
{
public async Task<Result<Uri>> ValidateAsync(string? raw, CancellationToken ct)
{
if (!Uri.TryCreate(raw, UriKind.Absolute, out var uri) || raw!.Length > 2048)
return Result<Uri>.Fail("url.invalid", "Enter a valid web address.");
if (uri.Scheme is not ("http" or "https"))
return Result<Uri>.Fail("url.scheme", "Only http and https links are allowed."); // no javascript:, data:, file:
if (uri.IsLoopback || uri.HostNameType == UriHostNameType.Dns && uri.Host.EndsWith(".internal", StringComparison.OrdinalIgnoreCase))
return Result<Uri>.Fail("url.host", "That address cannot be shortened.");
if (IPAddress.TryParse(uri.Host, out var ip) && !PublicAddress.IsPublic(ip)) // from Day 50
return Result<Uri>.Fail("url.host", "That address cannot be shortened.");
if (await reputation.IsMaliciousAsync(uri, ct))
return Result<Uri>.Fail("url.unsafe", "This link was flagged as unsafe.");
return Result<Uri>.Ok(uri);
}
}
app.MapPost("/api/links", async (CreateLink body, TargetUrlValidator validator, AppDb db, ClaimsPrincipal user,
IConfiguration cfg, CancellationToken ct) =>
{
var target = await validator.ValidateAsync(body.Url, ct);
if (!target.IsSuccess) return Results.Problem(target.Error!.Message, statusCode: 400);
string code;
if (body.Alias is { } alias)
{
if (!CodeGenerator.IsAllowedAlias(alias)) return Results.Problem("That alias is not allowed.", statusCode: 400);
code = alias;
}
else
{
// ToListAsync, not SingleAsync: NEXT VALUE FOR cannot appear inside the subquery that composing would add.
var n = (await db.Database.SqlQuery<long>($"SELECT NEXT VALUE FOR dbo.LinkSeq AS [Value]").ToListAsync(ct)).Single();
code = CodeGenerator.FromSequence(n, Convert.FromBase64String(cfg["Links:CodeKey"]!)); // key from Key Vault
}
db.Links.Add(new Link { Code = code, TargetUrl = target.Value!.AbsoluteUri, OwnerId = user.GetUserId(), ExpiresAt = body.ExpiresAt });
try { await db.SaveChangesAsync(ct); }
catch (DbUpdateException) { return Results.Problem("That alias is already taken.", statusCode: 409); } // primary key is the uniqueness guarantee
return Results.Created($"/api/links/{code}", new { code, shortUrl = $"https://sho.rt/{code}" });
}).RequireAuthorization().RequireRateLimiting("create-link");// Redirect: cache first, one primary-key read on a miss, temporary redirect, analytics off the hot path.
app.MapGet("/{code:regex(^[A-Za-z0-9_-]{{4,32}}$)}", async (string code, HybridCache cache, AppDb db, ClickChannel clicks, CancellationToken ct) =>
{
var link = await cache.GetOrCreateAsync($"link:{code}", async token =>
await db.Links.AsNoTracking().Where(l => l.Code == code && !l.IsDisabled)
.Select(l => new CachedLink(l.TargetUrl, l.ExpiresAt)).FirstOrDefaultAsync(token),
new HybridCacheEntryOptions { Expiration = TimeSpan.FromMinutes(10), LocalCacheExpiration = TimeSpan.FromMinutes(1) },
cancellationToken: ct);
if (link is null || (link.ExpiresAt is { } exp && exp < DateTimeOffset.UtcNow)) return Results.NotFound();
clicks.TryRecord(code); // in-memory channel, aggregated in the background
return Results.Redirect(link.TargetUrl, permanent: false); // 302: keeps analytics and revocation possible
}).AllowAnonymous().RequireRateLimiting("redirect");
// Takedown removes the row's effect immediately: disable it and evict the cache entry on every instance.
// await db.Links.Where(l => l.Code == code).ExecuteUpdateAsync(s => s.SetProperty(l => l.IsDisabled, true));
// await cache.RemoveAsync($"link:{code}");// React management UI: a small form, server errors mapped to fields (Day 55), and the link list with keyset paging (Day 24).
const { register, handleSubmit, setError } = useForm<{ url: string; alias?: string }>({ resolver: zodResolver(CreateLinkSchema) });
const create = useMutation({ mutationFn: (v) => request('/api/links', LinkSchema, { method: 'POST', body: JSON.stringify(v), headers: { 'Content-Type': 'application/json', 'X-CSRF': '1' } }),
onSuccess: () => qc.invalidateQueries({ queryKey: linkKeys.list(userId) }) });
// The short URL is shown as text and copied with navigator.clipboard, never injected as HTML.Walk through the failure modes. If Redis is down, the redirect falls through to SQL by primary key, which at 4,000 requests per second is still comfortable. If the analytics channel is full, clicks are dropped or sampled instead of delaying redirects. If the sequence is exhausted or the key is lost, codes must be regenerated consistently, so the key belongs in Key Vault with a documented backup, since losing it would risk collisions with existing codes only if the permutation changes, which is why the primary key still guarantees uniqueness.
Real-World Examples
- Link shorteners are well known as phishing and malware infrastructure because they hide the destination, and security teams and email gateways routinely expand and scan shortened links. Services such as Bitly and Google Safe Browsing integrations check destinations and disable flagged links, which is why abuse handling is part of the core design and not an afterthought.
- Google announced that it would stop creating goo.gl links in 2018 and later said that dormant links would stop working in 2025, then adjusted the plan after criticism to keep actively used links working. The episode shows the long-term obligation that comes with a shortener: links are embedded in documents and printed materials for years, so retirement is a decision with real cost to users.
Review Questions & Answers
The codes are sequential, so anyone can enumerate every link, including ones meant to be private or unlisted, by stepping through values. Scrambling the sequence with a keyed reversible permutation keeps uniqueness without collisions but makes codes unpredictable to anyone without the key.
A 301 is cached by browsers and intermediaries, reducing load but making later edits, takedowns, and click counting unreliable because repeat visitors never reach your server. A 302 or 307 is not cached that way, so every click reaches you, keeping analytics accurate and revocation immediate at the cost of more requests, which a cache absorbs easily.
Redirect latency is the product's main quality, and a slow or failing analytics store must not affect it. Writing an event to an in-memory channel or queue and aggregating in the background keeps the hot path to a cache lookup and a response, and if analytics falls behind, you can sample or drop events without breaking redirects.
Allow only http and https schemes to avoid javascript, data, and file links, reject loopback and private addresses to prevent abuse against internal systems, cap the length, and check reputation because shorteners are prime tools for phishing and malware. Re-checking periodically catches pages that become malicious after creation.