Endpoint Routes and Handlers

Sweet Tooth is oriented around RESTful APIs. You send GET, POST, PUT, and DELETE requests to paths like /todo-list and /todo-list/1 in order to perform CRUD operations. The corresponding request handlers are located in a namespace like sweet-tooth.todo-example.backend.endpoint.todo-list.

The sweet-tooth.todo-example.cross.endpoint-routes/expand-routes function lets you specify the names of namespaces that contain handlers and uses those to generate routes. Let’s generate some simple routes in a REPL and work our way up to more complex ones:

The function took a single keyword corresponding to a namespace’s name and generated two routes for it, one with the path "/todo-list" named :todo-lists and one with the path "/todo-list/{id}" `named `:todo-list. These paths and names are derived from the namespace name, with endpoint. as the default delimiter.

Routes are supposed to convey a request to a handler, and with reitit routes you designate a handler with the :handler key. The :handler key is conspicuously missing from the above routes. So how does this work?

The Sweet Tooth module :sweet-tooth.endpoint.module/liberator-reitit-router adds the :handler key to routes. It uses the metadata keys ::serr/ns and ::serr/type to construct a liberator request handler using a liberator decision map.

::serr/ns is used to find a liberator decision map. By default, these are defined in a var named decisions. If you look at sweet-tooth.todo-example.backend.endpoint.todo-list namespace you’ll see something like this (I’ve elided irrelevant code):

decisions is a map whose keys correspond to ::serr/type in the routes above: if a request for "/todo-list" is received, the ::serr/type value of :collection is used to look up the map of handlers under :collection in the decisions var. The request method (:get, :post, :put etc) is then used to look up the decision map for that method. The decision map is passed to a liberator function that returns a request handler. (If you’re unfamiliar with liberator this probably looks weird as all get out. I’ll explain liberator elsewhere, for now we’re just focusing on the relationship between routes and handlers.)

To summarize:

What if you only want to generate a :collection route or only want to generate a :member route? Routes can take an option map, and you can specify which routes to generate with the key ::serr/expand-with:

(I’ve switched from :sweet-tooth.todo-example.backend.endpoint.todo-list to :project.endpoint.todo-list because the latter is much shorter, and to show reinforce that everything up to endpoint. is ignored when generating paths and route names.)

Notice that the value of for ::serr/expand-with is [:collection] and only a :collection route was generated. You can try this with [:member] to see what happens. The default value for ::serr/expand-with is [:collection :member].

In this context, :collection and :member are names of route types. Each route type has an expansion strategy associated with. The expansion strategy includes:

In later sections you’ll see how to work with additional kinds of route types, include :singleton, :member children, and arbitrary types.

What if you want to create routes that match paths like the following?

The expand-routes function only performs route expansion when it encounters vectors where the first element is a keyword, like [:project.endpoint.admin.todo-list]. In addition to these namespace-based routes, you can also write plain ol' reitit routes. The next example matches a regular reitit route with a namespace route:

The regular route isn’t touched. One non-obvious consequence of this is that you’ll need to supply a :handler key yourself; Sweet Tooth uses the ::serr/ns and ::serr/type keys to construct a handler, but those are absent. You can add a handler as an integrant ref or by using the sweet-tooth.endpoint.utils/clj-kvar function:

The clj-kvar function returns the corresponding var during Clojure compilation and returns the keyword during ClojureScript compilation. This makes it easier to write routes that can cross-compile.

You should use an integrant ref if the handler needs to participate in integrant’s configuration system - if you need to initialize the handler with environment variables or system components, for example. Using clj-kvar would let you forego integrant initialization and keep your integrant config a little leaner.

What if you want to give multiple routes a prefix or otherwise want to apply options to multiple routes?

expand-routes takes a vector as its argument. Whenever it encounters a vector in that map, as it does with {::serr/path-prefix}, it adds that map as route options for all the routes that follow. If one group of routes need a set of common options that differs from another group of routes, you could write something like this:

Notice that todo routes have a different :id-key and they also don’t have the /api/v1 prefix. Whenever a new common options map ({:id-key :db/id}) is encountered, it replaces the previous map ({::serr/path-prefix "/api/v1"}).