Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 37 ยท Projects and Practice

Project: A Tiny Router and URL Shortener in Crystal

Build a small URL shortener in Crystal: a path router with parameters, base62 ids, JSON API, redirects and validation, with a runnable Ruby model of the logic.

A URL shortener is a perfect second project: tiny, useful and full of real web-service questions. A client posts a long address and gets back a short code such as /b3; visiting /b3 redirects to the original. You will write a path router with parameters, an id generator, validation, and the HTTP::Server glue from Building an HTTP Server.

The Crystal code is read-only on this site. The Ruby version runs the same router and shortener logic against fake requests, so you can experiment with every rule.

Design

TEXT
POST /shorten      body {"url": "https://example.com/very/long/path"}   -> 201 {"code": "b", "short": "/b"}
GET  /:code                                                              -> 302 Location: original url
GET  /:code/stats                                                        -> 200 {"code": "b", "hits": 3}
GET  /                                                                   -> 200 plain text help
flowchart TD
  R["Request"] --> RT["Router: match method + path"]
  RT -->|POST /shorten| S["Validate url, create code"]
  RT -->|GET /:code| L["Look up, count hit, redirect"]
  RT -->|GET /:code/stats| T["Return hits"]
  RT -->|no match| N["404"]

The router chooses a handler; the handlers share one in-memory store.

Step 1: short codes with base62

Numeric ids turn into short strings by writing the number in base 62 (digits plus lowercase and uppercase letters):

CRYSTAL
ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"

def encode(id : Int64) : String
  return "0" if id == 0
  digits = [] of Char
  while id > 0
    digits << ALPHABET[id % 62]
    id //= 62
  end
  digits.reverse.join
end

def decode(code : String) : Int64
  code.each_char.reduce(0_i64) { |acc, ch| acc * 62 + ALPHABET.index!(ch) }
end

Six characters already cover 62^6, about 56 billion links. Sequential ids are guessable, which is fine for a toy; a production service would shuffle the alphabet or use random codes and check for collisions.

Ruby Ruby stand-in: base62 codes

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 gets), it gets the next line from this box.

Step 2: a router with parameters

Rather than a long case, write a small router. A pattern such as /:code/stats is split into segments, and segments that start with : capture a value:

CRYSTAL
alias Handler = Proc(HTTP::Server::Context, Hash(String, String), Nil)

class Router
  record Route, method : String, segments : Array(String), handler : Handler

  def initialize
    @routes = [] of Route
  end

  def add(method : String, pattern : String, &handler : HTTP::Server::Context, Hash(String, String) -> Nil)
    @routes << Route.new(method, split(pattern), handler)
  end

  def dispatch(context : HTTP::Server::Context) : Bool
    path = split(context.request.path)
    @routes.each do |route|
      next unless route.method == context.request.method
      if params = match(route.segments, path)
        route.handler.call(context, params)
        return true
      end
    end
    false
  end

  private def split(path : String) : Array(String)
    path.split('/', remove_empty: true)
  end

  private def match(pattern : Array(String), path : Array(String)) : Hash(String, String)?
    return nil unless pattern.size == path.size
    params = {} of String => String
    pattern.zip(path) do |expected, actual|
      if expected.starts_with?(':')
        params[expected[1..]] = actual
      elsif expected != actual
        return nil
      end
    end
    params
  end
end

Routes are tried in order, so register fixed paths (/shorten) before parameter paths (/:code). match returns a hash of parameters or nil (a nilable return type again forces callers to handle failure).

Step 3: the shortener service

CRYSTAL
require "uri"

class Shortener
  record Entry, url : String, hits : Int32 = 0

  def initialize
    @entries = {} of String => Entry
    @next_id = 1_i64
  end

  def shorten(url : String) : String
    validate!(url)
    code = encode(@next_id)
    @next_id += 1
    @entries[code] = Entry.new(url)
    code
  end

  def visit(code : String) : String?
    entry = @entries[code]? || return nil
    @entries[code] = Entry.new(entry.url, entry.hits + 1)
    entry.url
  end

  def hits(code : String) : Int32?
    @entries[code]?.try(&.hits)
  end

  private def validate!(url : String)
    uri = URI.parse(url)
    unless {"http", "https"}.includes?(uri.scheme) && uri.host
      raise ArgumentError.new("Only absolute http(s) URLs are accepted")
    end
  end
end

Validation is a security duty: accepting javascript: or file: links would turn your shortener into an attack tool. Only http and https with a host are allowed.

Ruby Ruby stand-in: Router and Shortener together

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 gets), it gets the next line from this box.

Step 4: wire it to HTTP::Server

CRYSTAL
require "http/server"
require "json"

shortener = Shortener.new
router = Router.new

router.add("GET", "/") do |ctx, _|
  ctx.response.print "POST /shorten, then GET /:code\n"
end

router.add("POST", "/shorten") do |ctx, _|
  begin
    body = ctx.request.body.try(&.gets_to_end) || ""
    url = JSON.parse(body)["url"].as_s
    code = shortener.shorten(url)
    ctx.response.status = :created
    ctx.response.content_type = "application/json"
    ctx.response.print({code: code, short: "/#{code}"}.to_json)
  rescue ex : ArgumentError | JSON::ParseException | KeyError
    ctx.response.status = :bad_request
    ctx.response.print "Bad request: #{ex.message}"
  end
end

router.add("GET", "/:code/stats") do |ctx, params|
  if hits = shortener.hits(params["code"])
    ctx.response.content_type = "application/json"
    ctx.response.print({code: params["code"], hits: hits}.to_json)
  else
    ctx.response.status = :not_found
  end
end

router.add("GET", "/:code") do |ctx, params|
  if url = shortener.visit(params["code"])
    ctx.response.redirect(url)
  else
    ctx.response.status = :not_found
    ctx.response.print "Unknown code"
  end
end

server = HTTP::Server.new do |ctx|
  router.dispatch(ctx) || begin
    ctx.response.status = :not_found
    ctx.response.print "Not found"
  end
end

server.bind_tcp("0.0.0.0", ENV.fetch("PORT", "3000").to_i)
server.listen

Because the server uses one thread by default, the shared Shortener needs no lock. If you compile with -Dpreview_mt, wrap the store calls in a Mutex#synchronize (see select, Mutex and Parallelism).

Step 5: try it with curl

Terminal
curl -i -X POST localhost:3000/shorten -d '{"url":"https://example.com/docs"}'
# HTTP/1.1 201 Created   {"code":"1","short":"/1"}
curl -i localhost:3000/1
# HTTP/1.1 302 Found     Location: https://example.com/docs
curl localhost:3000/1/stats
# {"code":"1","hits":1}

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why register /shorten before /:code in the router?

    First match wins, so specific paths must come before parameter patterns that could swallow them.
  2. 2. Why does the shortener reject javascript: URLs?

    Open redirects to other schemes can run scripts or read local files.
  3. 3. What status code does ctx.response.redirect(url) send by default?

    redirect sets a Location header and a 302 status unless you pass another.
  4. 4. What makes the router's match return type Hash(String, String)?

    nil means 'this route does not fit', and callers must handle it.

Summary

  • A tiny router splits paths into segments and captures :name parameters.
  • Base62 turns a counter into a short, URL-safe code.
  • Validate every URL you accept; reply with proper status codes (201, 302, 400, 404).
  • Keep storage in one object; with parallel fibers protect it with a Mutex.
  • Extend it with expiry dates, persistence in SQLite and a custom alphabet.

Next: Project: A Worker Pool with Channels