Sub-resources — employeerepublic/yada-core 1.2.16

Sub-resources

Usually, it is better to declare as much as possible about a resource prior to directing requests to it. If you do this, your resources will expose more information and there will be more opportunities to utilize this information in various ways (perhaps serendipitous ones). But sometimes it just isn’t possible to know everything about a resource, up front, prior to the request.

A classic example is serving a changing directory of files. Each file might be a separate resource, identified by a unique URI and have different possible representations. Unless the directory’s contents are immutable, you should only determine the number and nature of files contained therein upon the arrival of a request. For this reason, yada has sub-resources. Sub-resources are resources that are created just-in-time when a request arrives.

Declaring sub-resources

Any resource can declare that it manages sub-resources by declaring a :sub-resource_ entry in its resource-model. The value of a sub-resource is a single-arity function, taking the request-context, that returns a new resource, from which a temporary handler is constructed to serve just the incoming request.

Sub-resources are recursive. A resource that is returned from a sub-resource function can itself declare that it provides its own sub-resources, ad-infinitum.

Path info

When routing, it is common for resources that provide sub-resources to match a set of URIs all starting with a common prefix, and extract the rest of the path from the request’s :path-info entry. This is achieved by declaring a :path-info? entry in the resource-model set to true.

(resource
  {:path-info? true
   :sub-resource
   (fn [ctx]
     (let [path-info (get-in ctx [:request :path-info])]
       (resource {…})))})

(For a good example of sub-resources, readers are encouraged to examine the code for yada.resources.file-resource to see how yada serves the contents of directories.)