Routes In Depth

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"}).

Reitit lets you to express path prefixes with data structures like

Personally, I have an aversion to using nested data structures to represent nested resources. I’ve found that it becomes a lot easier to get lost in navigating the data structures, and it can get difficult to determine what values might be cascading through the nested layers, or what the relationships among the layers might be. Ultimately what we’re producing is a lookup table, and I personally find it much easier to reason about such a table if there isn’t any nesting.