Skip to content
Tutorials Center
My learning

Topics

Lesson 59 of 66 ยท Projects

Project: URL Shortener Service

Build a URL shortener with Spring Boot: base62 ids, redirects, click counting, caching and rate limiting, with runnable plain-Java models of the core logic.

A URL shortener looks trivial: store a long link, hand out a short code, redirect when someone visits it. That simplicity hides a set of design questions that appear in almost every real service. How do you generate short unique codes? Which redirect status is correct? How do you count clicks without slowing down the redirect? How do you stop one client from flooding you?

In this project you build the service in Spring Boot and answer each question. The real Spring code is read-only here, since Boot and a database cannot run on this site. Three runnable stand-ins model the core ideas in plain Java: base62 ids, the redirect path with a cache and click counters, and a token-bucket rate limiter. If you have not read it yet, Project: Todo REST API shows the basic layering this project builds on, and Caching explains the cache annotations used below.

Requirements

What the service does

Shorten POST a long URL, get a short code back.
Redirect GET the code, receive a redirect to the target.
Count Track how often each link is used.
Protect Validate links and limit abuse.

Reads vastly outnumber writes, so the redirect path must be cheap.

1 / 2

The API has two endpoints:

Request Result
POST /api/links with {"url": "...", "alias": "optional"} 201 with the code; 400 for an invalid URL; 409 if the alias is taken; 429 if the client is too fast
GET /{code} 302 with a Location header; 404 if the code is unknown

Short codes with base62

A code that uses digits, upper-case and lower-case letters has 62 symbols per position. Seven characters give 62โท, about 3.5 trillion codes, which is enough for most services. Turning a database id into a code is just changing the number's base:

Java
public final class Base62 {

    private static final String ALPHABET =
        "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";

    private Base62() {
    }

    public static String encode(long value) {
        StringBuilder out = new StringBuilder();
        long remaining = value;
        do {
            out.append(ALPHABET.charAt((int) (remaining % 62)));
            remaining /= 62;
        } while (remaining > 0);
        return out.reverse().toString();
    }

    public static long decode(String code) {
        long value = 0;
        for (char c : code.toCharArray()) {
            int digit = ALPHABET.indexOf(c);
            if (digit < 0) {
                throw new IllegalArgumentException("Not a base62 character: " + c);
            }
            value = value * 62 + digit;
        }
        return value;
    }
}

Using the id as the code means no collisions and no retry loop: the database guarantees uniqueness. The weakness is that codes come out in order (1, 2, 3...), so anyone can walk through every link. If that matters, scramble the id with a reversible calculation before encoding it. Multiplying by a number that shares no factor with 62โท, modulo 62โท, is a bijection, and the multiplier's modular inverse undoes it. This is obfuscation, not encryption, so never rely on it for secrecy.

Java Base62 ids and reversible scrambling

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 IO.readln() or a Scanner), it gets the next line from this box.

The scrambled codes look random yet decode back to the exact id, and 100,000 ids never collide. In the Spring service, the id comes from the database, so creating a link takes two steps in one transaction: save the row to get the id, then compute and store the code.

The entity and the creation flow

Java
@Entity
@Table(name = "short_link", indexes = @Index(name = "ux_short_link_code", columnList = "code", unique = true))
public class ShortLink {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(length = 32, unique = true)
    private String code;

    @Column(nullable = false, length = 2048)
    private String targetUrl;

    private Instant createdAt = Instant.now();

    private long clicks;

    protected ShortLink() {
    }

    public ShortLink(String targetUrl) {
        this.targetUrl = targetUrl;
    }

    public void assignCode(String code) {
        this.code = code;
    }

    // getters omitted
}
Java
@Service
public class LinkService {

    private final ShortLinkRepository repository;

    public LinkService(ShortLinkRepository repository) {
        this.repository = repository;
    }

    @Transactional
    public ShortLink create(String url, String alias) {
        UrlPolicy.check(url);
        if (alias != null && repository.existsByCode(alias)) {
            throw new AliasTakenException(alias);
        }
        ShortLink link = repository.save(new ShortLink(url));
        link.assignCode(alias != null ? alias : Base62.encode(link.getId()));
        return link;
    }

    @Cacheable(cacheNames = "targets", key = "#code")
    public String targetFor(String code) {
        return repository.findByCode(code)
            .map(ShortLink::getTargetUrl)
            .orElseThrow(() -> new LinkNotFoundException(code));
    }
}

A shortener is a favorite tool of phishers, so validation is part of the design. A small policy class accepts only http and https URLs with a host, limits the length and rejects links that point at your own domain, which would create redirect loops:

Java
final class UrlPolicy {

    static void check(String url) {
        if (url == null || url.length() > 2048) {
            throw new InvalidUrlException("URL is missing or too long");
        }
        URI uri;
        try {
            uri = new URI(url);
        } catch (URISyntaxException e) {
            throw new InvalidUrlException("Not a valid URL");
        }
        String scheme = uri.getScheme();
        if (scheme == null || !(scheme.equals("http") || scheme.equals("https")) || uri.getHost() == null) {
            throw new InvalidUrlException("Only http and https links are allowed");
        }
    }
}

Never accept javascript:, data: or file: targets. Production services also check new links against abuse lists and provide a way to report and disable a link.

The redirect and why it is a 302

Java
@RestController
class RedirectController {

    private final LinkService links;
    private final ClickCounter clicks;

    RedirectController(LinkService links, ClickCounter clicks) {
        this.links = links;
        this.clicks = clicks;
    }

    @GetMapping("/{code:[0-9A-Za-z_-]{1,32}}")
    ResponseEntity<Void> redirect(@PathVariable String code) {
        String target = links.targetFor(code);   // cached
        clicks.record(code);                     // never cached
        return ResponseEntity.status(HttpStatus.FOUND)
            .location(URI.create(target))
            .build();
    }
}

The regular expression in the path restricts what the route matches, and more specific routes such as /api/links win over the pattern. The status matters: a 301 ("moved permanently") tells browsers and proxies to remember the target and skip your server next time, so later clicks are never counted and you can never change the destination. A 302 is not cached by default, which keeps every visit visible.

Notice the order of the two calls. If the click counting lived inside the @Cacheable method, every cache hit would skip it, and your counts would silently stop growing once a link became popular. Keep side effects outside cached methods. See Caching for the proxy rules behind this.

flowchart TD
    A["GET /aZ3k9"] --> B{"In the cache?"}
    B -- yes --> D["302 with Location"]
    B -- no --> C["Load from the database"]
    C --> E["Store in the cache"]
    E --> D
    D --> F["Count the click in memory"]

A hit never touches the database, and every request is counted either way.

The next stand-in models the whole redirect path: validation, aliases, an LRU cache with a small capacity, a database read counter and the click counters.

Java Redirects, an LRU cache and click counting

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 IO.readln() or a Scanner), it gets the next line from this box.

Five successful visits caused only four database reads, because the second docs visit was a cache hit. The last docs visit read the database again, since two other links had pushed it out of the two-entry cache (the fifth read in the totals is the unknown code). All five successful visits are counted, as the totals show. A real cache would be a Caffeine cache sized in the tens of thousands, with an expiry such as one hour: spring.cache.caffeine.spec=maximumSize=50000,expireAfterWrite=1h. Do not cache "not found" answers, because a link created a second later would still look missing.

Counting clicks without slowing the redirect

An update ... set clicks = clicks + 1 per redirect works, and it is safe because the increment happens inside the database, not as read-modify-write in Java:

Java
@Modifying
@Query("update ShortLink l set l.clicks = l.clicks + :n where l.code = :code")
int addClicks(@Param("code") String code, @Param("n") long n);

But a database write on every redirect turns a cheap read path into a write-heavy one. A better pattern counts in memory and flushes in batches:

Java
@Component
class ClickCounter {

    private final Map<String, LongAdder> pending = new ConcurrentHashMap<>();
    private final ShortLinkRepository repository;

    ClickCounter(ShortLinkRepository repository) {
        this.repository = repository;
    }

    void record(String code) {
        pending.computeIfAbsent(code, c -> new LongAdder()).increment();
    }

    @Scheduled(fixedDelay = 5000)
    @Transactional
    void flush() {
        for (String code : List.copyOf(pending.keySet())) {
            LongAdder adder = pending.remove(code);
            if (adder != null && adder.sum() > 0) {
                repository.addClicks(code, adder.sum());
            }
        }
    }
}

The price is that a crash can lose up to five seconds of counts. For analytics that is usually fine; if every click must be exact, write an event to a durable queue instead (see Messaging and Events Between Services). Scheduling is covered in Scheduling and Asynchronous Work.

Rate limiting creation

Without a limit, one script can create millions of links. The token bucket algorithm allows short bursts and a steady average. Each client has a bucket that holds up to a fixed number of tokens, refilled at a constant rate. A request needs one token. If the bucket is empty, the answer is 429 Too Many Requests with a Retry-After header.

Java A token-bucket 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 IO.readln() or a Scanner), it gets the next line from this box.

In Spring, a OncePerRequestFilter on POST /api/links does this, using the client address as the key:

Java
@Component
class CreateRateLimitFilter extends OncePerRequestFilter {

    private final RateLimiter limiter;

    CreateRateLimitFilter(RateLimiter limiter) {
        this.limiter = limiter;
    }

    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        return !(request.getMethod().equals("POST") && request.getRequestURI().equals("/api/links"));
    }

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
            FilterChain chain) throws ServletException, IOException {
        long waitSeconds = limiter.secondsUntilAllowed(request.getRemoteAddr());
        if (waitSeconds > 0) {
            response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
            response.setHeader("Retry-After", String.valueOf(waitSeconds));
            return;
        }
        chain.doFilter(request, response);
    }
}

Two cautions. Behind a proxy, getRemoteAddr() is the proxy's address, so configure server.forward-headers-strategy and trust the forwarded header only when your own proxy sets it, because clients can fake it. And an in-memory limiter counts per instance: with several instances, move the buckets to Redis or let a gateway enforce the limit. The filter mechanics are explained in Filters, Interceptors and Argument Resolvers.

Tests that matter

Round-trip tests catch the bugs that matter most in the id code, and a web slice test pins the redirect contract:

Java
class Base62Test {

    @Test
    void decodeUndoesEncode() {
        for (long id : new long[] {0, 1, 61, 62, 3844, Integer.MAX_VALUE, Long.MAX_VALUE}) {
            assertThat(Base62.decode(Base62.encode(id))).isEqualTo(id);
        }
    }
}

@WebMvcTest(RedirectController.class)
class RedirectControllerTest {

    @Autowired
    MockMvcTester mvc;

    @MockitoBean
    LinkService links;

    @MockitoBean
    ClickCounter clicks;

    @Test
    void knownCodeRedirectsAndIsCounted() {
        when(links.targetFor("docs")).thenReturn("https://example.com/docs");

        assertThat(mvc.get().uri("/docs"))
            .hasStatus(HttpStatus.FOUND)
            .headers().hasValue("Location", "https://example.com/docs");

        verify(clicks).record("docs");
    }
}

Also test a policy rejection (javascript: returns 400), the duplicate alias (409) and the rate-limit filter with a fake clock, as the stand-ins above do.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does the shortener answer with a 302 and not a 301?

    A permanent redirect can be remembered by clients. A temporary 302 keeps every visit flowing through your service.
  2. 2. What bug appears if click counting is placed inside the @Cacheable method?

    A cache hit returns the stored value without running the method, so any side effect inside it is skipped. Keep side effects outside cached methods.
  3. 3. What is the advantage of in-memory counters flushed every few seconds?

    Batching turns thousands of tiny writes into one update per link per interval. The trade-off is durability of the last interval.
  4. 4. A token bucket holds 5 tokens and refills 1 per second. A client sends 7 requests in the same instant. What happens?

    The bucket starts full, so a burst up to its capacity is allowed. Once it is empty, further requests wait for the refill.

Summary

  • Convert database ids to base62 for short, collision-free codes; scramble them reversibly if sequential codes are a problem, but do not treat that as security.
  • Validate targets: only http and https, a host, a length limit and no links to yourself.
  • Redirect with 302 so every click reaches you; cache the code-to-URL lookup and keep click counting outside the cached method.
  • Count clicks with an atomic SQL increment, in memory plus batched flushes when the volume is high.
  • Limit creation with a token bucket per client; use shared storage when you run several instances.
  • Test the id round trip, the redirect contract, the policy and the limiter.

Next: Project: Blog with Users and Roles.