Routing in Backend

-

Backend from First Principles: A Deep Dive into Routing

In our last deep dive, we explored the world of HTTP—the methods, headers, and status codes that form the language of the web. We learned that an HTTP method like GET or POST expresses the "what" of a request—it's the intent or action you want to perform.

But that's only half the story. Once a request with its intent arrives at the server, how does the server know where to direct it? How does it map that request to the correct piece of code?

This is the world of routing. If HTTP methods are the "what," then routing is the "where." It is the map of your backend application, guiding each incoming request to its precise destination.

Routing, at its core, is the mechanism for mapping a URL path and an HTTP method to a specific piece of server-side logic (a "handler").

The server takes the method (GET) and the route path (/api/users), combines them to find a unique match, and executes the associated handler to perform business logic, interact with a database, and ultimately return a response.

Let's explore the different types of routes and patterns that form the backbone of virtually every backend system.

The Building Blocks: Static vs. Dynamic Routes

1. Static Routes

A static route is a fixed, unchanging URL path. It's a constant string that always points to the same resource collection or endpoint.

Consider this request:

GET /api/books

And this one:

POST /api/books

In both cases, the route path /api/books is static. It doesn't contain any variable parts. However, the server treats them as two distinct endpoints because of their different HTTP methods.

  • GET /api/books maps to a handler that fetches and returns a list of all books.

  • POST /api/books maps to a different handler that creates a new book from the data in the request body.   

The combination of (Method + Static Route) creates the unique key for the routing map.

2. Dynamic Routes

A dynamic route contains one or more variable segments, often called path parameters. This allows you to create flexible endpoints that can handle a wide range of inputs without defining a separate route for each one.

Consider this request:

GET /api/users/123

In the server, the route definition would look something like this (the syntax is conventional across most frameworks like Express, FastAPI, or Axum):

/api/users/:id

The colon (:) signifies that id is a dynamic parameter. When a request comes in for /api/users/123, the server's router matches this pattern and understands that 123 is the value for the id parameter. The handler can then extract this value (123) to fetch the specific user from the database.

This makes our API semantic and human-readable: "Get the user with the ID 123."

Understanding Route Parameters: Path vs. Query

It's crucial to understand the two main ways we pass parameters in a URL.

Path Parameters (/users/:id)

As we just saw, path parameters are part of the URL path itself. They are used to identify a specific, unique resource.

  • GET /users/123: Gets the user with ID 123.

  • DELETE /products/xyz-987: Deletes the product with ID xyz-987.

They are integral to the path and define the resource's identity.

Query Parameters (/books?page=2&limit=10)

Query parameters are key-value pairs that appear after a question mark (?) in the URL. They are not used to identify a resource but rather to filter, sort, or paginate a collection of resources.

The GET method in HTTP doesn't have a request body. So, how do we send extra information like filtering options to the server? We use query parameters.

A common use case is pagination. Imagine you have 1,000 books in your database. You don't want to return them all at once.

  1. Initial Request: GET /api/books

    The server might return the first 20 books by default, along with metadata:

    JSON
    {
  "data": [ ... 20 books ... ],
  "pagination": {
    "total": 1000,
    "currentPage": 1,
    "totalPages": 50,
    "limit": 20
  }
}

  2. Next Page Request: To get the next page, the client uses query parameters.

    GET /api/books?page=2&limit=20

The server's handler for /api/books can read these query parameters (page=2, limit=20) and fetch the appropriate slice of data from the database. Query parameters give us a powerful way to modify the response for a collection without changing the core route.

Advanced Routing Patterns

1. Nested Routes

As applications grow, resources often have relationships with each other. Nested routes provide a clean, semantic way to express these hierarchical relationships.

Let's trace the hierarchy:

  • GET /api/users: Returns a list of all users.

  • GET /api/users/123: Returns the specific user with ID 123.

  • GET /api/users/123/posts: Returns all posts belonging to the user with ID 123.

  • GET /api/users/123/posts/456: Returns the specific post with ID 456 that belongs to user 123.

Each level of nesting drills deeper into the resource hierarchy, creating an API that is self-documenting and intuitive.

2. Route Versioning (/v1/)

What happens when you need to make a "breaking change" to your API? For instance, changing a field in your response from name to title. If you just make the change, you will break all existing clients (like mobile apps) that are expecting the old format.

Route versioning is the professional solution. You prefix your routes with a version number:

  • Version 1 (Old): GET /api/v1/products

    • Response: { "id": 1, "name": "My Product", "price": 100 }

  • Version 2 (New): GET /api/v2/products

    • Response: { "id": 1, "title": "My Product", "price": 100 }

This allows you to deploy new, breaking changes in v2 while keeping v1 running for older clients. You can then notify developers to migrate to the new version. Over time, you can deprecate and eventually shut down the older version once all clients have migrated.

3. Catch-All Routes (/*)

What happens if a user requests a route that doesn't exist, like /api/v3/products? By default, the server might just hang or return an unhelpful error.

A catch-all route (often written as /*) is a route defined at the very end of your routing configuration. It acts as a safety net, matching any request that hasn't been matched by the more specific routes above it.

The handler for this route typically returns a user-friendly 404 Not Found response, providing a much better experience than a generic server error.

Conclusion

Routing is the skeleton of your backend application. By mastering these fundamental patterns—static vs. dynamic, path vs. query parameters, nesting, and versioning—you gain the ability to look at any backend codebase and instantly understand its structure. You're no longer just looking at code; you're reading the map. This skill is universal, transferable across any language or framework, and a true mark of a first-principles engineer.

Comments

Post a Comment

Popular posts from this blog

HTTP from First Principles

-
Image
HTTP from First Principles: The Complete Guide for Backend Engineers As backend engineers, we operate in a world of complex systems. But if we start discussing every single component, we could be stuck for years. Instead, we'll focus on the topics that appear in the vast majority—say, 90%—of all codebases. With that in mind, let's talk about the HTTP protocol , the primary medium through which our browsers talk to our servers. While many protocols exist for client-server communication, HTTP is one of the most ubiquitous, and mastering it is non-negotiable. The Two Foundational Ideas of HTTP At the heart of the HTTP protocol lie two ideas that define its architecture and behavior. 1. Statelessness: The Protocol with No Memory Statelessness means that the server has no memory of past interactions . Each HTTP request is treated as a new, unrelated event. Self-Contained Requests: Because the server doesn't remember past requests, each new request must carry all the necessary i...
Read more

Authentication and Authorization

-
Image
The Ultimate Guide to Authentication & Authorization Understanding Authentication & Authorization: A Journey from Handshakes to Hashing We encounter it every single day. From logging into our favorite social media apps to accessing our work platforms, the gates of digital entry are guarded by two crucial concepts: authentication and authorization . While often used interchangeably, they serve distinct but equally vital roles in securing our online experiences. Let's break them down: Authentication: Simply put, authentication answers the question, "Who are you?" It's the process of verifying your identity, proving that you are indeed who you claim to be. Think of it as showing your ID to get into a club. Authorization: Once your identity is confirmed, authorization steps in to answer, "What can you do?" It determines your permissions and capabilities within that system. After showing your ID, authorization dictates whether you're allowed on the...
Read more

The Anatomy of a Backend Request: Layers, Middleware, and Context Explained

-
Backend from First Principles: The Request Life Cycle (Handlers, Services, Repositories, & Middleware) As a backend engineer, your primary job is to manage the flow of data through your application, from the moment a client's request arrives until the final response is sent. While this may sound like a single, simple task, a robust, production-grade backend relies on a layered architecture and a set of critical tools to handle this process securely and efficiently. This guide will break down the essential components of a backend system, tracing the journey of a request and explaining the fundamental patterns that every engineer should know: Handlers, Services, Repositories, Middleware, and Request Context. Now, in this part, we take an deep dive into the server's internal workings. With the request successfully received and its data initially validated and transformed, we explore the internal request life cycle : how the data flows through distinct architectural layers, an...
Read more