Defining Routes

Welcome

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.

What You Will Learn

After reading this guide, you will be able to:

Define routes
Parse parameters from URLs
Connect routes to handlers
Apply interceptors along a route
Use constraints to ensure a route is invoked correctly
Generate links for a route during a request to that route
Generate links for other routes

Guide Assumptions

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

Getting Help If You’re Stuck

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

Where We Are Going

In Your First API, 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:

Serve static resources
Use multiple parameters
Use wildcards to match subtrees
Support multiple verbs

We will also generate URLs from routes and parameters.

Before We Begin

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.

A Note About Routing Syntax

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.

Some of the older examples may still use the older, "terse", syntax. All newer examples, such as this one, use the table syntax; it’s much simpler, and easier to understand at a glance.

The older syntaxes (yes, there’s an even older one called "verbose") are still supported; if you come across very old code, check the Routing Quick Reference for full details.

Defining a Route: The Bare Minimum

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

["/users" :get view-users]

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

An Interceptor record
A request handler function (really a special case of interceptor)
A few other cases still maintained for backwards compatibility that we’ll ignore

Building handlers

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

["/users" :get (make-view-users-handler db-conn)]

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:

["/echo" :get (fn [request] {:status 200 :body request}) :route-name :echo]

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.

Path Parameters

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:

["/users/:user-id" :get view-users]

will match any of the following requests:

/users/abacab
/users/miken
/users/12345
/users/mike%20n

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

{:path-params {:user-id "miken"}}

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.

Catch-all Parameters

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:

["/users/:user-id/profile/*subpage" :get view-user-profile]

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:

{:path-params {:user-id "miken" :subpage "photos/blue-wig.jpg"}}

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

Using this kind of parameter requires that there’s some data to match; a URL of /users/miken/profile or /users/miken/profile/ will not match, because there’s no data to extract as the :subpage path parameter.

Query Parameters

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:

{:query-params {:q "blog"}}

Verbs

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

:get
:put
:post
:delete
:patch
:options
:head
:any

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.

Interceptors

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.

["/user/:user-id/private" :post [inject-connection
                                 auth-required
                                 (body-params/body-params)
                                 view-user]]

In this example, inject-connection and auth-required are application-specific interceptors. 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 queued into the context for later execution (after any interceptors already in the queue).

Common interceptors

The "terse" syntax uses hierarchically nested routes to reuse interceptors on subtrees. The table based syntax gives up that feature, but still allows you to compose interceptors:

;; Make a var with the common stuff
(def common-interceptors [inject-connection
                          auth-required
                          (body-params/body-params)])

;; inside a call to table-routes
["/user/:user-id/private" :post (conj common-interceptors view-user)]

This leaves your code in charge of composing interceptors using ordinary Clojure data manipulation.

Constraints

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:

["/user/:user-id" :get view-user :constraints {:user-id #"[0-9]+"}]

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:

(def numeric #"[0-9]+")
(def user-id {:user-id numeric})

["/user/:user-id" :get  view-user   :constraints user-id]
["/user/:user-id" :post update-user :constraints user-id]

Considering Constraints

The thing about constraints is that they are not used to distinguish between otherwise identical routes. They are not for disambiguation. Rather, constraints are used to reject requests that do match the rest of the route but do not match the constraints.

What happens after such a rejection depends on which router is being used.

Router	Behavior on Failed Constraint
Prefix tree	Abort and return a 404 response
Map tree	Abort and return a 404 response
Linear search	Continue searching the remaining routes

Router

Behavior on Failed Constraint

Prefix tree

Abort and return a 404 response

Map tree

Abort and return a 404 response

Linear search

Continue searching the remaining routes

Be cautious about using path constraints.

Experience has shown that constraints result in a worse experience for users of your API. Generally, it is better to validate path and query parameters inside your route (in an interceptor or handler for the specific route) so that proper errors could be returned to the client, rather than a generic, and perhaps misleading, 404 NOT FOUND response.

As an alternative to using path constraints, you could define a validating interceptor:

(def user-id-validator
  (interceptor
     {:name ::user-id-validator
      :enter (fn [context]
               (if (re-matches #"[0-9]+" (get-in context [:request :path-params :user-id]))
                 context
                 (assoc context
                   :response {:status 400
                              :body "user-id must be numeric"})))}))

This interceptor could be placed into the interceptor list for any route that has a user-id in the path, and will uniformly abort any request (with a 400 Bad Request status code) if the user-id is not numeric.

Route names

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:

["/user" :get view-user :route-name :view-user-profile]

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

Path - String
Verb - keyword (e.g., :get)
Interceptors - interceptor, handler function, or vector of interceptors
Route name clause (:route-name your-route-name)
Constraints clause (:constraints constraint-map)

Default Route Names

You’ll notice that most of the examples above omit the :route-name clause. When there is no explicit route name, Pedestal will pick one for you. It uses the :name of the last interceptor in the interceptor vector.

Route names must be unique, so if you use the same interceptor in the last position in multiple routes, you’ll have to supply the route name.

Using Route Names to Distinguish Handlers

Suppose you have a single interceptor or handler that deals with multiple verbs on the same path. Maybe it’s a general API endpoint function or a function created by another library. If you just try to make multiple rows in a table, you will get errors:

;;; This won't work; both rows get the same automatic
;;; route name and an exception is thrown.
["/users" :get user-api-handler]
["/users" :post user-api-handler]

The best approach is to simply provide a unique route name to each route that shares the handler.

["/users" :get  user-api-handler :route-name :users-view]
["/users" :post user-api-handler :route-name :user-create]

Generating URLs

In addition to routing incoming requests, the routing data is also available to the application 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.

URL generation

The url-for-routes function takes the expanded routing table ^[1] and creates and returns a function that uses the data to craft URL strings.

The function accepts a route name and optional arguments and returns a URL that can be used in a hyperlink.

(def app-routes
   (route/expand-routes (1)
     (table/table-routes (2)
       [["/user"                   :get  user-search-form]
        ["/user/:user-id"          :get  view-user        :route-name :show-user-profile]
        ["/user/:user-id/timeline" :post post-timeline    :route-name :timeline]
        ["/user/:user-id/profile"  :put  update-profile]])))

(def url-for (route/url-for-routes app-routes))

(url-for :user-search-form)
;; => "/user"

(url-for :view-user :params {:user-id "12345"})
;; => "/user/12345"

1	`url-for-routes` requires a fully expanded routing table.
2	Explicitly calling `table-routes` is a choice; the alterative is to put the routes in a set.

Any leftover entries in the :params map that do not correspond to path parameters get turned into query string parameters. If you want more control, you can give the generator the specific arguments :path-params and :query-params.

Request-specific URL generation

The url-for-routes 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:

In the context map, using the :url-for key
In the request map (inside the context), using the same :url-for key
In a private dynamic variable in the io.pedestal.http.route namespace

The private variable allows the url-for function to operate from any interceptor (or handler) code.

Form Route Verbs

url-for only returns URLs. The function form-action-for-routes takes a route table and returns a function that accepts a route-name (and optional arguments) and returns a map containing a URL and an HTTP verb.

(def form-action (route/form-action-for-routes app-routes))

(form-action :timeline :params {:user-id 12345})
;; => {:method "post", :action "/user/:user-id/timeline"}

A form action function will (by default) convert verbs other than GET or POST to POST, with the actual verb added as a query string parameter named _method:

(form-action :update-profile :params {:user-id 12345})
;; => {:method "post", :action "/user/12345/profile?_method=put"}

This behavior can be disabled (or enabled for url-for functions) and the query string parameter name can be changed. All of these settings can be modified when an url-for or form-action function is created or when it is invoked.

The _method parameter is used for verb smuggling.

Using Routes in a Service

The Your First API guide goes inot create detail about routes inside a Pedestal application, showing how to build up a number of routes, using different paths and HTTP methods, into a consistent, REST API.

Restrictions on Wildcards and Path Parameters

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.

Wrapping Up

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 Routing Quick Reference.

1. This is what’s returned from table-routes.