Skip to content

Latest commit

 

History

History
325 lines (231 loc) · 11 KB

dhal_specification.mkd

File metadata and controls

325 lines (231 loc) · 11 KB
Raw
layout
default

DHAL - Dtime Hypertext Application Language

A lean hypermedia type based on HAL with extensions for dtime

Discussion Group

DHAL is a superset of the HAL media type. The hal mailing list is available here: HAL-discuss mailing list.

DHAL Differences

DHAL is a superset of HAL. This document is a fork of the original HAL specification available here: http://stateless.co/hal_specification.html

DHAL is currently only defined with a JSON variant.

As it is intended to be a superset, most of this document will describe HAL. DHAL-specific sections will be marked with an asterisk (*), and are listed here for quick reference:

  • DHAL is json only.
  • the _template attribute is now part of the formal definition
  • A link may have the href-template instead of href attribute set. If it is set, it will be a URI template and should conform with the rules in rfc 6570: http://tools.ietf.org/html/rfc6570. To conform with the current draft of HAL, the href-template may also be stored in the href - if both are present, the href-template is preferred.
  • A link may have the href-vars set if a uri template is available. It is optional, as uri templates can be parsed to discover this information, but additional metadata relating to the field may be supplied in this field.

General Description

HAL is a simple way of linking with JSON.

It provides a set of conventions for expressing hyperlinks to, and embeddedness of, related resources - the rest of a HAL document is just plain old JSON.

HAL is a bit like HTML for machines, in that it is designed to drive many different types of application. The difference is that HTML is intended for presenting a graphical hypertext interface to a 'human actor', whereas HAL is intended for presenting a machine hypertext interface to 'automated actors'.

This document contains a formalised specification of HAL. For a friendlier, more pracitcal introduction to HAL you can read this article: JSON Linking with HAL

HAL has two main components: Resources and Links.

  • Resources can have their own state, links, and other embedded resources.
  • Links have a link relation (rel) that signals how to interpret the target resource.

Below is an image illustrating HAL's information model:

The HAL Information model

DHAL is a single media type (application/vnd.dtime.dhal+json) with which applications are meant to be developed and exposed as sets of traversable link relations.

Instead of using linkless JSON, or spending time developing a custom media type, you can just use HAL and focus on creating link relations to drive your application.

HAL encourages the use of link relations to:

  • Identify links and embedded resources within the representation
  • Infer the expected structure and meaning of target resources
  • Signalling what requests and representations can be submitted to target resources

Examples

Here is how you could represent a collection of orders with the JSON variant of HAL:

{% highlight javascript %} { "_links": { "self": { "href": "/orders" }, "next": { "href": "/orders?page=2" }, "search": { "href-template": "/orders?id={order_id}", "href-vars": { "order_id": { "title": "Order Id", "href": "/params/order_id" } } } }, "_template": { "type" => "order", "properties" => { "total" => {"type" => "float", "required" => true}, "currency" => {"type" => "string", "required" => true} } } }, "_embedded": { "order": [ { "_links": { "self": { "href": "/orders/123" }, "customer": { "href": "/customer/bob", "title": "Bob Jones [email protected]" } }, "total": 30.00, "currency": "USD", "status": "shipped", "placed": "2011-01-16", "_embedded": { "basket": { "_links": { "self": { "href": "/orders/123/basket" } }, "items": [ { "sku": "ABC123", "quantity": 2, "price": 9.50 },{ "sku": "GFZ111", "quantity": 1, "price": 11 } ] } } },{ "_links": { "self": { "href": "/orders/124" }, "customer": { "href": "/customer/jen", "title": "Jen Harris [email protected]" } }, "total": 20.00, "currency": "USD", "status": "processing", "placed": "2011-01-16", "_embedded": { "basket": { "_links": { "self": { "href": "/orders/124/basket" } }, "items": [ { "sku": "KLM222", "quantity": 1, "price": 9.00 },{ "sku": "HHI50", "quantity": 1, "price": 11.00 } ] } } } ] } } {% endhighlight %}

Code

For HAL parsing:

Compliance

An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements is said to be "conditionally compliant."

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Media Type Identifiers*

  • application/vnd.dtime.dhal+json

    The JSON based variant of DHAL

Components*

HAL provides hypertext capabilities via three elements:

  1. Resources

    For expressing the embedded nature of a given part of the representation.

  2. Links

    For expressing 'outbound' hyperlinks to other, related resources.

  3. Templates*

    For expressing how to build new resources

Shared Attributes

The Resource and Link elements share the following attributes:

  • href

    REQUIRED

    For indicating the target URI.

    href corresponds with the 'Target IRI' as defined in Web Linking (RFC 5988)

  • rel

    REQUIRED

    For identifying how the target URI relates to the 'Subject Resource'. The Subject Resource is the closest parent Resource element.

    This attribute is not a requirement for the root element of a HAL representation, as it has an implicit default value of 'self'

    rel corresponds with the 'relation parameter' as defined in Web Linking (RFC 5988)

    rel attribute SHOULD be used for identifying Resource and Link elements in a HAL representation.

  • name

    OPTIONAL

    For distinguishing between Resource and Link elements that share the same rel value. The name attribute SHOULD NOT be used exclusively for identifying elements within a HAL representation, it is intended only as a 'secondary key' to a given rel value.

Note: the following attributes have corresponding target attributes' as defined in Web Linking (RFC 5988)

  • hreflang

    OPTIONAL

    For indicating what the language of the result of dereferencing the link should be.

  • title

    OPTIONAL

    For labeling the destination of a link with a human-readable identifier.

Link Attributes

The following are attribute definitions applicable only to HAL's Link element.

  • href

    REQUIRED

    This attribute MAY contain a URI template. Whether or not this is the case SHOULD be indicated to clients by the rel value.

Resource Attributes

The following are attribute definitions applicable only to HAL's Resource element.

  • href

    REQUIRED

    Content embedded within a Resource element MAY be a full, partial, summary, or incorrect representation of the content available at the target URI. Applications which use HAL MAY clarify the integrity of specific embedded content via the description of the relevant rel value.

Templates*

Templates should conform with JSON-schema http://tools.ietf.org/html/draft-zyp-json-schema-03.

Constraints

The root of a HAL representation MUST be a Resource with an href that corresponds to the effective request URI of the resource being represented.

DHAL in JSON (application/vnd.dtime.dhal+json)*

Note: click the following for a more accessible explanation of HAL in JSON

Further details on the JSON variant of HAL:

  • Resources are represented as objects
  • Resource objects have two reserved properties: _links, _template and _embedded
  • The _links property contains Link objects against keys that match their relation
  • The _template property contains a json schema template
  • The _embedded property contains embedded Resource objects against keys that match their relation
  • Resource objects MUST have a self link (_link.self) which indicates the URI of the embedded resource
  • Relations with one corresponding Resource/Link have a single object value, relations with multiple corresponding HAL elements have an array of objects as their value.

Minimum Valid Representation

JSON

{% highlight javascript %} { "_links": { "self": { "href": "http://example.com/" } } } {% endhighlight %}

Recommendations

Using URIs for Link relation values

Link relation values used in HAL representations SHOULD be URIs which, when dereferenced, provide relevant details. This helps to improve the discoverability of your application.

For JSON, a 'curie' link can be used like so:

{% highlight javascript %} { ... '_links' : { 'curie': { 'href' : 'http://example.com/rels/{relation}', 'name': 'ex' }, ... }, ... } {% endhighlight %}

Acknowledgements

Thanks to Darrel Miller and Mike Amundsen for their invaluable feedback.

Notes/todo

Transclusion ala esi for JSON variant? XML can reuse ESI?