Reference — employeerepublic/yada-core 1.2.16

Protocols

yada defines a number of protocols. Existing Clojure types and records can be extended with these protocols to adapt them to use with yada.

`yada.protocols.ResourceCoercion`

(coming soon)

Every HTTP method is implemented as a type which extends the yada.methods.Method protocols. This way, new HTTP methods can be added. Each type must implement the correct semantics for the method, although yada comes with a number of built-in methods for each of the most common HTTP methods.

Many method types define their own protocols so that resources can also help determine the behaviour. For example, the built-in GetMethod type uses a Get protocol to communicate with resources. The exact semantics of this additional protocol depend on the HTTP method semantics being implemented. In the Get example, the resource type is asked to return its state, from which the representation for the response is produced.

`yada.body.MessageBody`

Message bodies are formed from data provided by the resource, according to the representation being requested (or having been negotiated). This removes a lot of the formatting responsibility from the resources, and this facility can be extended via this protocol for new message body types.

Built-in types

There are numerous types already built into yada, but you can also add your own. You can also add your own custom methods.

Files

The yada.resources.file-resource.FileResource exposes a single file in the file-system.

The record has a number of fields.

Field

Type

Required?

Description

file

java.io.File

yes

The file in the file-system

reader

Map

A file reader function that takes the file and selected representation, returning the body

representations

A collection of maps

The available representation combinations

The purpose of specifying the reader field is to apply a transformation to a file’s content prior to forming the message payload.

For instance, you might decide to transform a file of markdown text content into HTML. The reader function takes two arguments: the file and the selected representation containing the media-type.

(fn [file rep]
  (if (= (-> rep :media-type :name) "text/html")
    (-> file slurp markdown->html)
    ;; Return unprocessed
    file))

The reader function can return anything that can be normally returned in the body payload, including strings, files, maps and sequences.

The representation field indicates the types of representation the file can support. Unless you are specifying a custom reader function, there will usually only be one such representation. If this field isn’t specified, the file suffix is used to guess the available representation metadata. For example, a file with a .png suffix will be assumed to have a media-type of image/png.

Directories

The yada.resources.file-resource.DirectoryResource record exposes a directory in a filesystem as a collection of read-only web resources.

The record has a number of fields.

Field

Type

Required?

Description

dir

java.io.File

yes

The directory to serve

custom-suffices

Map

A map relating file suffices to field values of the corresponding FileResource

index-files

Vector of Strings

A vector of strings considered to be suitable to represent the index

A directory resource not only represents the directory on the file-system, but each file resource underneath it.

The custom-suffices field allows you to specify fields for the FileResource records serving files in the directory, on the basis of the file suffix.

For example, files ending in .md may be served with a FileResource with a reader that can convert the file content to another format, such as text/html.

(yada.resources.file-resource/map->DirectoryResource
  {:dir (clojure.java.io "talks")
   :custom-suffices {"md" {:representations [{:media-type "text/html"}]
                           :reader markdown-reader}}})

Appendix A: Reference

Resource model schema

Handler schema