Mason Cook Book

How can a client discover relevant resources at runtime?

Use links represented in a @controls element with URLs to the relevant resources.

Use links to bind different resources together. Links represent relations such as "parent-of" between resources. The use of links in representations allows a client to discover related resources on the fly - instead of hard coding the client with knowledge of the URL structures used.

Building clients that discover URLs on the fly opens up for some really nice improvements:

Here we have the representation of a single issue from the issue tracker. It contains links to itself (the "self" linke), its parent project (the "up" link) and its own list of attachments (the "is:attachments" link):

Custom control names are too long and clutters readability of the JSON source. How can the it be made more readable?

Use CURIES (Compact URIs) to shorten control names.

Compact URIs or "CURIEs" for short is a standard way of shortening URIs as described in http://www.w3.org/TR/2009/CR-curie-20090116/. A CURIE is comprised of two components, a prefix and a reference. The prefix is separated from the reference by a colon (:) - like for instance "is:attachments" where "is" is the prefix and "attachments" is the reference. In Mason the prefix refers to a namespace declaration in the @meta section.

A CURIE is expanded into a full URI by looking up the prefix in the namespace declarations and substituting the prefix with the "name" value of the namespace (and removing the colon).

All CURIEs in Mason MUST be expanded to URIs by the client before looking for control names.

CURIES are not used for href values in hypermedia controls.

Here we have a namespace declaration that maps from "is" to "http://elfisk.dk/mason/issue-tracker/reltypes.html#" and one single link named "is:attachments". If we expand the prefix "is" we get the link name "http://elfisk.dk/mason/issue-tracker/reltypes.html#attachments" which in this representation is equivalent to "is:attachments".

How can a client discover URLs that depends on values supplied by the client?

Use templated URLs represented as a @controls element with a templated href value.

URL templates instruct clients (at runtime) about URL construction from a well known set of variables - as for instance a query where the client is supposed to include query parameters in the URL and then GET that resource.

A URL template in Mason is declared as a @control element with the isHrefTemplate property set to true. This indicates to the client that the related href value is to be interpreted as a URL template.

The rules for variable substitution in URL templates are described in RFC 6570 - URI Template.

A JSON schema definition can be used to described the variables used in the URL template. This is not a required feature as the variable names can be parsed from the template itself but a JSON schema makes it possible to generate automatic user interfaces on the fly - similar to HTML forms but without all the layout features.

All the values for the template variables should be represented in a JSON object. Variable names are then supposed to be JSONPath expressions (without leading slashes) that refer to properties in the JSON object.

The example here contains the URL template control named "is:issue-query" which represents a query for issues in the common issue tracker example. It refers to three different variables text, severity and pid. All of the variables are described in the embedded JSON schema definition.

If the client supplies the variables as a JSON object as the one below then the expanded URL becomes "http://issue-tracker.org/issues-query?text=ABC&severity=3&project=17".

How can a client discover available actions and their operational details?

Use @controls elements to describe each possible action including both HTTP method and JSON payload.

Hypermedia APIs that allow clients to modify content needs some way to represent the possible operations. At the most basic level all that is needed is a link:

But links does not tell clients about the expected HTTP operation (POST, PUT, …​) and neither does it say anything about the expected payload - what data should be included and how should it be encoded? For this purpose Mason includes the properties "method", "encoding", "schema", "schemaUrl" and "template".

If we include "method" and "encoding" in the example then we get this:

With the above information clients can now discover what HTTP method to use (POST) and how the payload should be encoded (plain JSON).

But knowing the encoding alone is not enough - clients should also be able to discover what the expected payload is. This can be done using JSON schema which is a format for describing JSON data structures. Such a schema can either be embedded directly in the hypermedia control using "schema" or referred to by a URL using "schemaUrl".

Here is how an embedded schema could describe the payload needed to "update stuff":

It is also possible to include default values for input - or rather a complete template for the payload. This is covered in the next recipe How to supply default values for input data.

The same argument goes for the schema description of the payload: if the client knows how to look for the "update-stuff" control then it surely also knows what the payload is expected to be.

So why should we bother with method, encoding and schema at runtime? First of all because it enables client developers to explore and discover all parts the API. This can be a huge help when learning how an API works for the first time. It will reduce developer frustration and help them getting started with the API.

Unfortunately none of the standard browsers understand Mason (but they can still be used to render Mason as JSON structures) so a special browser is needed. At the time of writing there is only a Windows based implementation which can be found here https://github.com/JornWildt/Mason/wiki/Generic-Mason-browser.

This is how the issue tracker demo represents hypermedia controls for updating and deleting a single issue:

How can default values for input data be represented?

Include default values in the "template" property of a hypermedia control.

A hypermedia control for creating new items may need to include default values to present to the end user. This could of course be included as part of the API data itself but Mason includes a standard option for handling this kind of thing - the template property of a hypermedia control. This property defines a template for the data to be sent and clients are required to take this template and merge it with other input before sending the result or resolving URL templates.

Consider a hypermedia control for adding a new issue to an issue tracker. It could look somewhat like the one below with a title, a URL, the HTTP method and request encoding details:

In order to supply default values to the client we now add the template object that contains two properties containing the default values for the issue title and severity:

The client is now expected to process this as follows:

How can a client discover operations that include file uploads?

Use a @controls element with the encoding json+files.

It is sometimes relevant to include one or more binary documents and some related JSON data in a server request in order to store those documents on the server together with the JSON data. This could for instance be a blog post with associated images or a new issue in the issue tracker with associated documentation. But how should the client encode such documents and data in one request and how does the server inform the client about it?

For this purpose Mason inctroduces the json+files encoding scheme that allows clients to send both a JSON object and a set of binary documents. This scheme requires the client to send all documents and the JSON object as multipart/form-data where each part represents either a document or the JSON object. This is identical to how HTML forms handle file uploads except that the whole data set must be JSON encoded instead of sending each JSON object property as a separate part.

For the server to inform the client of the expected encoding scheme it must of course use a @controls element with encoding set to json+files. But it may also include a jsonFile property (string) that identifies the part containing the JSON data plus a files property (array) describing the set of possible documents to send.

The common issue tracker example allows clients to create new issues with attached documents. For this purpose it includes the following hypermedia control:

What the above example means is:

As a result the client might send a request like the one below: