The optional :id entry of the resource model gives the resource a unique identity. You can use whatever you like for the value, but it should be unique. A namespaced keyword is typical:

The main reason for giving your resources an identity is for creating hyperlinks targeting your resource. For example, this is how you would create a URL to the resource.

An example with a parameter:

This feature is only available if your resources are declared in a bidi hierarchical route structure. Otherwise, the URL cannot be determined.

Optionally, a resource can contain a textual description. This should be used for any descriptive text that applies to the resource as a whole (rather than individual methods, which can contain their own descriptions).

The description and summary values are used in generated Swagger descriptions and can be used for any other purpose you like.

The :access-control entry can be used to restrict access to a resource and provide security. It encompasses authentication and authorization, if necessary across multiple realms. It also determines the circumstances that the resource can be accessed from different origins for browser interaction (CORS) as well as defining other security protections.

Multiple authentication schemes are supported, such as Basic, JWT and OAuth2.

Access control and security are fully described in the security chapter.

You can define various properties on a resource. These can be thought of as a resource’s metadata, information about a resource (rather than the resource’s state).

It is possible to specify a complete map of constant properties, if they are all known prior to a request. This is rare, and usually it’s necessary to provide a function that will be called during the processing of a request.

Certain properties, such as :exists? and :last-modified are special and used by yada to determine responses.

For example, if you know how to determine the date that your resource was last modified, you should return this date in the :last-modified entry of a map containing your resources’s properties. Doing so will enable yada's logic for conditional requests, for instance, allowing it to return 304 Not Modified responses when appropriate.

More information can be found in [properties].

Web requests can contain parameters that can influence the response and yada can capture these. This is especially useful when you are writing APIs.

There are different types of parameters, which you can mix-and-match:

There are benefits to declaring these parameters explicitly:

Parameter declaration, validation and coercion is a big topic and fully covered in the parameters chapter.

Resources have physical forms called representations. A resource can declare all the representations it supports.

Typically, a representation will have a designated content type, such as text/html or application/json, which tells the receiver how to process it.

If the content type of a representation begins with text/, it might also have a given charset, indicating how the bytes transferred should be turned into text.

Some representations will also indicate whether the content is compressed (called the encoding) and maybe the language used.

It is often useful to distinguish between outward representations that can be produced and the inward representations that can be consumed.

The :produces entry in the resource model declares the representations of the resource that can be produced.

Where there is more than one representation that can be produced, yada negotiates which type, if any, is actually produced taking into account the declared preferences of the user agent. This process is known as content negotiation.

The :consumes entry declares the incoming representations that the resource is able to accept. Some HTTP methods allow requests to contain bodies. Here there is no content negotiation, since the user agent will tell the server the content type of the body it is sending.

More details can be found in the representations chapter.

The :methods entry is a map, where each key is a keyword that corresponds to an HTTP method.

There is no restriction on the methods you can declare.

The value of each method entry is also a map, which has the following structure:

Each method has a specific prescribed behaviour, called the method’s semantics, which usually described in a particular RFC document (but it’s also fine to define your own).

Method semantics for core HTTP methods are built-in to yada but it’s possible to add your own via a Clojure protocol.

Many method semantics will involve a call to the function you declare in the :response entry, which is responsible for constructing the response, but if you’re not sure you should check the description for the actual method you’re using in the methods chapter.

By default, yada will produce error messages and stack traces for various status codes. If you wish to override this behaviour, you must provide alternatives via the :responses entry of the resource map.

The path-info? entry is a boolean flag which indicates whether the resource expects a path-info.

Imagine your URI path is /dir/abc/foo.txt. You may want to partially match this path such that the resource is called for all URIs that begin with /dir/. In this case, abc/foo.txt would be set as the 'path-info' in the request map.

The reason we might want to indicate this on the resource is to tell our router that a partial match is required, and to give us access to the remaining path.

Sometimes we cannot know the properties of a given resource up-front. For example, imagine you are serving files from a file-system. It is impossible to determine which resources will be present when the request arrives, and therefore which properties and content attributes should be declared.

To support such dynamic resources, yada allows the declaration of a function, as the value of the :sub-resource key, that will be called when the request arrives. The return value of the sub-resource function must return the actual resource.

This feature is commonly used together with path-info to provide dynamic 'groups' of related resources.

The :logger entry can declare a function which is called whenever a request is processed and the response is about to be returned to the web-server. This allows you to log all requests to a file, for instance.

yada is built on a chain of interceptors that are processed asynchronously. For most cases, the default interceptor chain will suffice, but sometimes it is necessary to add to this chain, or modify it in some way, on a resource-by-resource basis. This is achieved by providing an alternative interceptor chain via the :interceptor-chain and :error-interceptor-chain entries.

The handler created by yada works by constructing a series of internal functions called interceptors.

When a request is received, the handler creates a new instance of an object known as the request context, and its idiomatic symbol is ctx.

Each interceptor is a single-arity function that takes this request context as an argument, returning the same request context or a modified copy.

Here’s an interceptor which adds some information into the request context:

On each request, the request context is 'threaded' through a 'chain' of interceptors, the result of each interceptor being used as the argument to the next.

One of the entries in the request context is :response, which contains the Ring response that will be returned to the web server. Any interceptor can modify this (or any other value) in the request context.

Here’s an example of a request context during the handling of a request:

The request context is not just passed to interceptors, but to functions you can declare in your resource.