Skip to content
Tutorials Center
My learning

Topics

Lesson 61 of 72 ยท Projects

Project: A URL Shortener

Build a URL shortener in Flask: base62 short codes, URL validation, 302 redirects, atomic click counts, a stats endpoint and a rate limiter, all tested in the browser.

A URL shortener turns https://example.com/some/very/long/path?with=params into something like https://sho.rt/4c92. It sounds like a toy, yet it touches many real web-development questions: how do you generate compact identifiers, which redirect status should you use, how do you count visits without losing updates, and how do you stop one client from flooding your service?

In this project you will build the whole thing in one file: a base62 encoder, a small SQLite table, a JSON endpoint that creates links, a redirect route that counts clicks, a stats endpoint and a rate limiter. Everything runs in the browser through Flask's test client, so you can press Run on each step and watch the app behave.

Plan the app

The service needs three endpoints:

Method and path What it does
POST /api/links Takes {"url": "..."}, stores it, returns the short code
GET /<code> Looks up the code, counts the click, redirects
GET /api/links/<code> Returns the target URL and the click count

The central idea is to let the database assign an integer id to each link, and to turn that integer into a short string. The integer is unique by construction, so the string is too, and no collision check is needed.

flowchart LR
    A["POST /api/links<br/>{url}"] --> B{"Valid http(s) URL?"}
    B -- no --> C["400 error"]
    B -- yes --> D["INSERT row, id = 42"]
    D --> E["code = base62(42 + OFFSET)"]
    F["GET /code"] --> G["id = decode(code) - OFFSET"]
    G --> H{"Row found?"}
    H -- no --> I["404"]
    H -- yes --> J["clicks = clicks + 1"]
    J --> K["302 redirect to stored URL"]

Creating a link turns an id into a code; following a link turns the code back into an id.

Step 1: base62 encoding

Decimal uses ten digits, hexadecimal uses sixteen. A short code can use far more symbols and still be safe in a URL: the digits, the lowercase letters and the uppercase letters give 62. Converting a number to base 62 works exactly like converting to any other base: repeatedly divide, and collect the remainders.

Python Base62 encode and decode

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Seven characters already give about 3.5 trillion codes, far more than most services will ever create. decode raises ValueError for a character outside the alphabet; the route will use that to answer 404 for garbage such as /favicon.ico.

Pure sequential ids have two drawbacks. The first link would be 1, which looks silly, and anyone can walk through 1, 2, 3, ... to discover every link. Adding a fixed offset fixes the first problem, and mentioning the second honestly matters: if links must be private, use random codes (for example secrets.token_urlsafe(5)) and retry on the rare collision. This project keeps the sequential design because it makes the data flow easy to see.

Step 2: the app

The app below keeps its SQLite database in memory and creates everything inside a create_app() function, as described in The Application Factory. A real deployment would open one connection per request, as shown in Using sqlite3 with Flask; here a single shared connection keeps the demo short.

Read the code in three parts. is_valid_url is the gatekeeper: only http and https URLs with a host are accepted. That single check blocks javascript: and data: links, which would otherwise turn your service into a tool for attacking visitors. create_link returns 201 for a new link and 200 when the same URL was already stored, so the same input always yields the same code. follow converts the code back to an id, increments the counter and redirects.

Python The shortener, end to end

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A few decisions in this code deserve a closer look.

302, not 301. A 301 Moved Permanently response may be cached by the browser forever, so repeat visits would skip your server and never be counted. 302 Found asks the browser to come back each time. If you do not need analytics and want to save traffic, 301 (or 308 for a method-preserving permanent redirect) is a legitimate choice.

clicks = clicks + 1 runs inside the database. The tempting alternative, reading the number into Python, adding one and writing it back, loses updates when two visitors click at the same moment. Letting SQL do the arithmetic makes the increment atomic.

The database owns uniqueness. The UNIQUE constraint on url guarantees one row per address even if two requests arrive together. The lookup before the insert is a convenience; the constraint is the safety net. A production version would also catch sqlite3.IntegrityError for that race.

Unknown input becomes 404. The find_link helper handles characters outside the alphabet, ids that do not exist, and spellings like 01abc that decode to the same number as 1abc but are not the code you issued. Without the canonical check, one link would answer on many URLs.

Step 3: limit abusive clients

Public endpoints that write data attract bots. A rate limiter caps how many requests one client may make in a time window and answers 429 Too Many Requests beyond it, with a Retry-After header that says when to try again.

The simplest design is a fixed window: remember when each client's window started and how many requests it has made. The class below takes its clock as a parameter. That is a handy testing trick, because the test can move time forward instantly instead of waiting a minute.

Python A fixed-window rate limiter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Client A is allowed three requests and refused the next two; client B is unaffected because limits are tracked per key. Thirty seconds later client A is still blocked, because the window has not ended; at 61 seconds a fresh window starts and the request succeeds.

This stand-in has real limits you should know about:

  • It lives in one process's memory. With four worker processes, each keeps its own counts, so the effective limit is four times higher. Production setups keep counters in a shared store such as Redis, usually through a library like Flask-Limiter.
  • The hits dictionary grows with every new client. A real limiter removes expired entries.
  • A fixed window allows a burst at the boundary: three requests at second 59 and three more at second 61. Sliding windows and token buckets smooth that out.
  • Behind a reverse proxy, request.remote_addr is the proxy's address unless you configure ProxyFix (see Deployment); otherwise every visitor shares one bucket.

To protect the shortener, decorate create_link with @rate_limited(limiter). Following links is cheap and read-mostly, so many services limit creation strictly and redirects loosely.

Ideas to extend it

  • Store created_at and show the newest links on an admin page.
  • Let a signed-in user choose a custom alias, with a reserved-word list (api, admin) so aliases cannot shadow your routes. See Building a Login System.
  • Check submitted URLs against a blocklist, since shorteners are popular with phishers.
  • Record each click in its own table (time, referrer) for charts, and aggregate with GROUP BY.
  • Cover the endpoints with tests like the ones in Testing Flask Apps with pytest. The test client calls above are already most of the way there.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does the shortener answer with 302 instead of 301?

    Permanent redirects are cached aggressively. A temporary redirect makes the browser ask your server every time, which keeps the click counter accurate.
  2. 2. What is the advantage of UPDATE links SET clicks = clicks + 1?

    Reading the count into Python and writing it back lets two requests overwrite each other. Doing the arithmetic in SQL closes that window.
  3. 3. Why does is_valid_url allow only http and https schemes?

    A shortener redirects to whatever it stored. Restricting the scheme stops it from becoming a delivery channel for script URLs.
  4. 4. A rate limiter keeps its counters in a Python dictionary and the app runs with four worker processes. What happens?

    Process memory is not shared. Use a shared store such as Redis when you run more than one worker.

Summary

  • A database id turned into base62 gives short, unique, URL-safe codes without collision checks; add an offset or use random codes if sequential ids are a problem.
  • Validate that submitted URLs use http or https and have a host before storing them.
  • Use 302 when every visit must reach your server, 301/308 when it should not.
  • Increment counters in SQL (clicks = clicks + 1) and let a UNIQUE constraint guarantee uniqueness.
  • Make the decode path strict: invalid characters and non-canonical spellings are 404s.
  • A rate limiter keyed by client address answers 429 with Retry-After; inject the clock so tests need no sleeping, and move counters to shared storage in production.

Next: Project: Users and Login, where you combine hashed passwords, sessions and roles into a complete sign-in system.