reitit

Reitit optimizes coercion middleware by compiling it against specific routes. The middleware is only mounted if the route explicitly defines :coercion along with either :parameters or :responses.

If a route lacks these keys, the coercion middleware chain will be empty for that route, reducing overhead. You can verify the mounted middleware for a specific route by inspecting the router using reitit.core/match-by-name.

(require '[reitit.core :as r])

;; Querying the compiled middleware chain for a route
(-> (ring/get-router app)
    (r/match-by-name ::plus)
    :result :post :middleware
    (->> (mapv :name)))
; => [::mw/coerce-exceptions ::mw/coerce-request ::mw/coerce-response]

;; A route without coercion defined will have no mounted middleware
(-> (ring/get-router app)
    (r/match-by-name ::ping)
    :result :get :middleware)
; => []

OpenAPI supports reusable schema objects via $ref. Reitit automatically generates these reusable schema objects for Malli :refs and vars. This allows multiple endpoints to reference the same schema, which is also rendered in a dedicated section in Swagger UI.

Note: As of version 0.7.2, reusable schema objects are not generated for Plumatic Schema or Spec.

Standard Reitit frontend routers require you to manually store and pass the router instance to every call.

To simplify this, use the reitit.frontend.easy wrapper. It manages the router instance internally and automatically passes it to all calls, which is suitable for most applications since a browser typically only has one active event handler for page changes.

In nested route trees, route data is accumulated from the root down to the leaves using meta-merge.

• Default behavior: Collections are appended.
• Overriding behavior: You can use metadata to change how data is merged. Use ^:prepend, ^:replace, or ^:displace on the target data to control the merge strategy.

(def router
  (r/router
    ["/api" {:interceptors [::api]}
     ["/ping" ::ping]
     ["/admin" {:roles #{:admin}}
      ["/users" ::users]
      ["/db" {:interceptors [::db]
              :roles ^:replace #{:db-admin}}]]]))

;; The /api/admin/db route will have :roles #{:db-admin} 
;; because ^:replace was used, overriding the parent's #{:admin}.

When using multiple middleware injection points, they execute in the following order (from outermost to innermost):

1. Top-level middleware (passed as the second argument to ring-handler).
2. Top-level route data middleware (defined in the :data key of the router).
3. Parent route middleware (defined in the route data of a parent path).
4. Route-specific middleware (defined in the route data of the matched path).
5. The Handler.

Example of execution order:

(def app
  (ring/ring-handler
    (ring/router
      ["/api" {:middleware [[wrap :3-parent]]}
       ["/get" {:get handler
                :middleware [[wrap :4-route]]}]]
      {:data {:middleware [[wrap :2-top-level-route-data]]}})
    nil
    {:middleware [[wrap :1-top]]}))

;; Resulting execution order for /api/get:
;; [:1-top :2-top-level-route-data :3-parent :4-route :handler]

Reitit allows you to define handlers for specific HTTP methods. You can place handlers at the top level (applying to all methods for that path) or under specific method keys (:get, :head, :patch, :delete, :options, :post, :put, or :trace).

• Top-level handler: Used if no method-specific handler is found.
• Method-level handler: Only catches the specified method.
• :options method: Enabled by default for all paths to support CORS.

Example:

(def app
  (ring/ring-handler
    (ring/router
      ["/all" handler] 
       ["/ping" {:name ::ping
                 :get handler
                 :post handler}]])))

Reitit prevents multiple routes from sharing the same name. If you define routes with duplicate names (e.g., using ::name syntax), reitit.core/router will throw a CompilerException with an ex-info containing the conflicting names.

Note: Unlike path conflicts, there is currently no way to disable or override name conflict resolution.

(require '[reitit.core :as r])

(def routes
  [["/ping" ::ping]
   ["/admin" ::admin]
   ["/admin/ping" ::ping]])

;; This will throw: CompilerException clojure.lang.ExceptionInfo: Router contains conflicting route names:
;; :reitit.core/ping
;; -> /ping
;; -> /admin/ping
(r/router routes)

Reitit supports two main styles for path parameters: colon syntax (:id) and bracket syntax ({id}).

Path Parameters

• Standard parameters: Use :name or {name}.
• Qualified keyword parameters: Use {user/id} or {:user/id} to allow keys with slashes or colons in the resulting parameter map.
• Catch-all parameters: Use *path or {*path} to match the remainder of the path.

Syntax Rules

• Colon syntax (:id): Parameters must end with a slash / or the end of the path string. They cannot be embedded in the middle of a string segment (e.g., file-:id.txt is not supported via colon syntax).
• Bracket syntax ({id}): Parameters can start and stop anywhere. The character immediately following the closing bracket acts as the terminator.
• Slash-free routing: Reitit supports paths without slashes, such as broker.{customer}.{device}.