Fork me on GitHub

Resource definition

A liberator resource is a ring handler and adheres to the ring contract. However, as a developer you will not work with the ring interface, but instead provide functions for decision points, actions and handlers.

resource and defresource

A resource is created using the functions resource which returns a function that is a ring handler. You can also use the defresource macro which binds the function to a var.

(defresource foo :handle-ok "This is ok")

;; this is the same as

(def foo (resource :handle-ok "This is ok")

The resource takes a sequence of keys and values. The values are functions that accept a single parameter, the context, or values that will be treated like a constant function.

;Option A
:handle-ok (fn [context] "We can use a function.")

;Option B
:handle-ok "We can also use a plain value"

Liberator uses three types of functions: decisions, actions and handlers.

Base implementation since 0.11.0

You can optionally pass a map as the first argument to a resource definition. The values in the map are used when no other value is specified for a key:

(def resource-defaults
  {:handle-not-found (fn [_] "Ops.")
   :authorized? (fn [_] ...)})

(defresource foo resource-defaults :handle-ok "This is ok")

;; this is the same as

(defresource foo
  :handle-ok "This is ok"
  :handle-not-found (fn [_] "Ops.")
  :authorized? (fn [_] ...))

Parameterized resources

Routing libraries like compojure support the extraction and binding of request parameters from the URL. This frees the developer from extracting the parameters from the request in the resource functions and typically enhances the code legibility.

With liberator you can use resource and simply close over the parameter, however, liberator simplifies this with parameterized resources.

(defresource parameterized [x]
  :handle-ok (fn [_] (format "This is x: %s" x)))

(defroutes params
  ;; these are equivalent:
  (ANY "/a/:x" [x] (fn [req] (resource :handle-ok (fn [_] (format "This is x: %s" x)))))
  (ANY "/b/:x" [x] (parameterized x)))