reitit

A fast data-driven router for Clojure(Script).

• Simple data-driven route syntax
• Route conflict resolution
• First-class route data
• Bi-directional routing
• Pluggable coercion (malli, schema & clojure.spec)
• Helpers for ring, http, pedestal & frontend
• Friendly Error Messages
• Extendable
• Modular
• Fast

Presentations:

• Reitit, The Ancient Art of Data-Driven, Clojure/North 2019, video
• Faster and Friendlier Routing with Reitit 0.3.0
• Welcome Reitit 0.2.0!
• Data-Driven Ring with Reitit
• Reitit, Data-Driven Routing with Clojure(Script)

Status: stable

Hi! We are Metosin, a consulting company. These libraries have evolved out of the work we do for our clients. We maintain & develop this project, for you, for free. Issues and pull requests welcome! However, if you want more help using the libraries, or want us to build something as cool for you, consider our commercial support.

Full Documentation

There is #reitit in Clojurians Slack for discussion & help.

Main Modules

• metosin/reitit - all bundled
• metosin/reitit-core - the routing core
• metosin/reitit-ring - a ring router
• metosin/reitit-middleware - common middleware
• metosin/reitit-spec clojure.spec coercion
• metosin/reitit-malli malli coercion
• metosin/reitit-schema Schema coercion
• fi.metosin/reitit-openapi OpenAPI apidocs *
• metosin/reitit-swagger Swagger2 apidocs
• metosin/reitit-swagger-ui Integrated Swagger UI
• metosin/reitit-frontend Tools for frontend routing
• metosin/reitit-http http-routing with Interceptors
• metosin/reitit-interceptors - common interceptors
• metosin/reitit-sieppari support for Sieppari
• metosin/reitit-dev - development utilities

... * This is not a typo; the new reitit-openapi was released under the new, verified fi.metosin group. Existing modules will continue to be released under metosin for compatibility purposes.

Extra modules

• reitit-pedestal support for Pedestal

Latest version

All main modules bundled:

[metosin/reitit "0.10.1"]

Optionally, the parts can be required separately.

Reitit requires Clojure 1.11 and Java 11.

Reitit is tested with the LTS releases Java 11, 17, 21 and 25

Quick start

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

(def router
  (r/router
    [["/api/ping" ::ping]
     ["/api/orders/:id" ::order]]))

(r/match-by-path router "/api/ping")
; #Match{:template "/api/ping"
;        :data {:name ::ping}
;        :result nil
;        :path-params {}
;        :path "/api/ping"}

(r/match-by-name router ::order {:id 2})
; #Match{:template "/api/orders/:id",
;        :data {:name ::order},
;        :result nil,
;        :path-params {:id 2},
;        :path "/api/orders/2"}

Ring example

A Ring routing app with input & output coercion using data-specs.

(require '[muuntaja.core :as m])
(require '[reitit.ring :as ring])
(require '[reitit.coercion.spec])
(require '[reitit.ring.coercion :as rrc])
(require '[reitit.ring.middleware.exception :as exception])
(require '[reitit.ring.middleware.muuntaja :as muuntaja])
(require '[reitit.ring.middleware.parameters :as parameters])

(def app
  (ring/ring-handler
    (ring/router
      ["/api"
       ["/math" {:get {:parameters {:query {:x int?, :y int?}}
                       :responses  {200 {:body {:total int?}}}
                       :handler    (fn [{{{:keys [x y]} :query} :parameters}]
                                     {:status 200
                                      :body   {:total (+ x y)}})}}]]
      ;; router data affecting all routes
      {:data {:coercion   reitit.coercion.spec/coercion
              :muuntaja   m/instance
              :middleware [parameters/parameters-middleware ; decoding query & form params
                           muuntaja/format-middleware       ; content negotiation
                           exception/exception-middleware   ; converting exceptions to HTTP responses
                           rrc/coerce-request-middleware
                           rrc/coerce-response-middleware]}})))

Valid request:

(-> (app {:request-method :get
          :uri "/api/math"
          :query-params {:x "1", :y "2"}})
    (update :body slurp))
; {:status 200
;  :body "{\"total\":3}"
;  :headers {"Content-Type" "application/json; charset=utf-8"}}

Invalid request:

(-> (app {:request-method :get
          :uri "/api/math"
          :query-params {:x "1", :y "a"}})
    (update :body jsonista.core/read-value))
; {:status 400
;  :headers {"Content-Type" "application/json; charset=utf-8"}
;  :body {"spec" "(spec-tools.core/spec {:spec (clojure.spec.alpha/keys :req-un [:spec$8974/x :spec$8974/y]), :type :map, :leaf? false})"
;         "value" {"x" "1"
;                  "y" "a"}
;         "problems" [{"via" ["spec$8974/y"]
;                      "path" ["y"]
;                      "pred" "clojure.core/int?"
;                      "in" ["y"]
;                      "val" "a"}]
;         "type" "reitit.coercion/request-coercion"
;         "coercion" "spec"
;         "in" ["request" "query-params"]}}

More examples

• reitit-ring with coercion, swagger and default middleware
• reitit-frontend, the easy way
• reitit-frontend with Keechma-style controllers
• reitit-http with Pedestal
• reitit-http with Sieppari

All examples are in https://github.com/metosin/reitit/tree/master/examples

External resources

• Simple web application using Ring/Reitit and Integrant: https://github.com/PrestanceDesign/usermanager-reitit-integrant-example
• A simple Clojure backend using Reitit to serve up a RESTful API: startrek. Technologies include:
  • Donut System
  • next-jdbc
  • JUXT Clip
  • Flyway
  • HoneySQL
  • Babashka
• https://www.learnreitit.com/
• Lipas, liikuntapalvelut: https://github.com/lipas-liikuntapaikat/lipas
• Implementation of the Todo-Backend API spec, using Clojure, Ring/Reitit and next-jdbc: https://github.com/PrestanceDesign/todo-backend-clojure-reitit
• Ping CRM, a single page app written in Clojure Ring, Reitit, Integrant and next.jdbc: https://github.com/prestancedesign/clojure-inertia-pingcrm-demo

More info

Check out the full documentation!

Join #reitit channel in Clojurians slack.

Roadmap is mostly written in issues.

Special thanks

• Existing Clojure(Script) routing libs, especially to Ataraxy, Bide, Bidi, calfpath, Compojure, Keechma and Pedestal.
• Compojure-api, Kekkonen, Ring-swagger and Yada and for ideas, coercion & stuff.
• Schema and clojure.spec for the validation part.
• httprouter for ideas and a good library to benchmark against

License

Copyright © 2017-2023 Metosin Oy

Distributed under the Eclipse Public License, the same as Clojure.