Defining Routes

This guide takes us past the basics of getting started. It deals with a part of Pedestal that you will touch quite often: routing.

A key problem in any backend service is directing incoming requests to the right bit of code. As an industry, we’ve settled on the term "routing" to describe how a service understands a request’s URL and invokes a matching function.

There’s a flip side to routing, though, which is generating URLs to put into links and hrefs. If we’re not careful, link generation can create hard-to-find coupling between different parts of a service.

Pedestal addresses both parts of this problem with the same feature.

After reading this guide, you will be able to:

This guide assumes that you understand HTTP requests and URLs. In particular, we make no effort to explain URL-encoding or query strings.

We’ll take this in small steps. If you get stuck at any point in this guide, please submit an {repo_root}/docs/issues[issue] about this guide or hop over to the mailing list and raise your hand there.

In your-first-api.adoc, we defined a handful of routes for a basic REST style API. It’s time to dig deeper and understand what we can do with this flexible and powerful part of Pedestal.

We will work with routes that:

We will also generate URLs from routes and parameters.

This guide will use Leiningen to generate and build a template project. If you haven’t already installed it, please take a few minutes to set it up.

Since Pedestal was first unveiled, we’ve gone through a couple of iterations on the routing syntax. So far, these iterations have all been additive. Prior to release 0.5.0, guides and samples all used the "terse" syntax, which is written as a triply-nested vector. The terse syntax is powerful but not easy.

Release 0.5.0 introduced a new syntax we call the "table" syntax. It is more wordy and has some repetition from row to row, but it also has some advantages:

The "terse" and "verbose" syntax are both still supported, until we hear from the community. We’ve also put some effort into better error messages when dealing with the terse format.

See the reference:routing-quick-reference.adoc for full details.

The simplest route has just a URL, an HTTP verb, and a handler:

In this case, view-users is anything that can be resolved as an interceptor:

There’s nothing special about using a symbol in the handler’s position. You could call a function that returns an interceptor:

That call to make-view-users-handler is nothing special. Clojure will evaluate it when you build the route table. Just make sure it returns something that can be resolved as an interceptor.

That also means you can use anonymous functions as handlers. Here’s another way we could implement an "echo" function:

Every route must have a route name, but in most cases, Pedestal can "figure out" a reasonable value. Here,the route name clause is necessary here because an anonymous function has nothing that Pedestal can use to infer a route name.

The URL in a route doesn’t have to be just text, often important request information is included in the URL, rather than query parameters. The URL from the route is actually pattern used to match URLs.

The URL pattern can include any number of segments to capture as parameters. Any segment that looks like a keyword will be captured in the :path-params map in the request.

So the route:

will match any of the following requests:

When the request reaches our view-users handler, it will include a map like this:

The path parameters are always delivered as strings. The strings are HTTP decoded for you, but are not otherwise converted.

A single path parameter only matches one segment of a URL. One segment is just the part between '/' characters. So the route above will not match /users/miken/profile/photos/blue-wig.jpg.

What if our user IDs are all numeric? It would be convenient if the route would only match when the URL meets a valid pattern in the path parameters. That’s the job of Constraints, discussed below.

What if you actually do want to match any number of segments after a path? In that case, you use a catch-all parameter. It looks like a path parameter, except it has an asterisk instead of a colon:

Now this route does match the URL /users/miken/profile/photos/blue-wig.jpg and, as you might have guessed, the matching segments are still delivered as path parameters in the request map:

As the subpage path parameter demonstrates, catch-all parameters are strings containing the remaining path segments.

You don’t need to do anything in the route to capture query parameters. They are automatically parsed and passed in the request map, under the :query-params key. Like path parameters, query parameters are always delivered as HTTP-decoded strings.

For example, an HTTP request with for the URL:

/search?q=blog

will have this in the request map:

So far, all our examples have used :get as the HTTP verb. Pedestal supports the following verbs:

These should look familiar, except for :any. The :any keyword is a wildcard that allows a route to match any request method. That gives a handler the opportunity to decide whether a request method is allowed or not.

So far, all our examples have used just one handler function. But one of Pedestal’s key features is the ability to create a chain of interceptors. The route table allows you to put a vector of interceptors (or things that resolve to interceptors) in that third position.

In this example, inject-connection and auth-required are application-specific interceptors. api:body-params[ns=io.pedestal.http.body-params] is a Pedestal function that returns an interceptor. view-user is a request-handling function.

When a request matches this route, the whole vector of interceptors gets pushed onto the context.

As a convenience, you can supply a map of constraints, in the form of regular expressions, that must match in order for the whole route to match. This handles that case from before, where we wanted to say that user IDs must be numeric.

You tell the router about constraints by supplying a map from parameter name to regular expression:

Notice the :constraints keyword. That is required to tell the router that the following map is to be treated as constraints.

Like the interceptor vector, the constraint map is just data. Feel free to build it up however you like…​ it doesn’t have to be a map literal in the route vector:

Every route must have a unique name. Pedestal uses route names for the flip side of route matching: URL generation. You can supply a route name in the route vector:

A route name must be a keyword. Most commonly, it is a namespace-qualified keyword.

The route name comes before :constraints, so if you have both, the order is as follows

In addition to routing, route tables are also used for URL generation. You can request a URL for a given route by name and specify parameter values to fill in. This section describes URL generation, starting with how routes are named.

The api:url-for-routes[ns=io.pedestal.http.route] function provides a global URL generator. Within a single request, the request map itself can provide a URL generator. This generator allows you to create absolute or relative URLs depending on how the request was matched.

When the routing interceptor matches a request to a route, it creates a new URL generator function that closes over the request map. This function is stored in three places:

The private variable allows the api:url-for[ns=io.pedestal.http.route] function to operate from any interceptor (or handler) code.

Up until now, we’ve looked at individual routes or a small handful of them. Now let’s see how to connect them to a Pedestal service.

Well, that means we probably need a service to put them in. Time to fire up leiningen. Pedestal provides a leiningen template to generate new projects. Find a nice spot to keep your work and run

Looks like the template generated some good stuff. project.clj defines the new service’s dependencies and build instructions. Dockerfile lets you package this service as a Docker container. Capstanfile is a similar thing to compile this service into a unikernel application with OSv.

For now, the parts we really want to see are under src/myapp.

These two source files define a production-ready Pedestal service. All it serves right now as an "About" page, so we need to make some improvements before we ship it.

server.clj supplies the main entry point. service.clj defines the behavior of the service itself. These are starting points, though. Over time, you will certainly add more files and factor behavior out of these two. For now, we need to open up service.clj and make some changes.

Here is what the template generated for us (as of version 0.5.1, at least. Details may differ slightly in yours.)

We will make this look more like the route table from your-first-api.adoc.

Notice the use of :list-id and :item to extract parts of the URL. Right now, each of those can contain any sequence of characters. Anything at all. Suppose we need to restrict them to numbers. That means we need to add constraints.

Here we’ve added a constraints clause to each of the routes with parameters. To make sure all the routes obey the same rules, we can factor those rules out into a value that we attach to each route.

One thing we haven’t demonstrated so far is the ability to match all of a URL’s string. You might do this if you need to create a URL hierarchy with arbitrary depth. That is the purpose of a wildcard URL like this:

Maybe this is for a manager to see every single TODO ever assigned to anyone in the organization. Seems perfectly reasonable.

This wildcard route will match anything that starts with /org/. Interceptors will receive a request with the path parameter :todos bound to everything that followed /org/. It is up to those interceptors to parse and interpret the URL.

The map tree router is by far the fastest router in Pedestal. Part of how it gets that speed, though, is by forbidding the use of dynamic path segments like wildcards and path parameters.

If your routes include any of them, then even if you request the map tree router, Pedestal will fall back to using the (still pretty fast) prefix tree router.

This guide covered route definitions, from the most basic possible case all the way to the most complex. It demonstrated the use of the table routing syntax and showed how to use them in a real service. Finally, it demonstrated the use of wildcard routes and discussed when to use them and their tradeoffs.

For more details, see the reference:routing-quick-reference.adoc.