mikekelly / hal_specification

HAL Specification

HAL - Hypertext Application Language

A lean hypermedia type

HAL is a simple way of linking with JSON or XML.

It provides a small set of conventions on top of JSON and XML for expressing hyperlinks to, and embeddedness of, related resources.

The spec is here: hal_specification.md.

For a friendlier, more practical introduction to HAL you can read this article: JSON Linking with HAL.

The JSON variant of HAL (application/hal+json) has now been published as an internet draft: draft-kelly-json-hal.

Discussion Group

If you have any questions or feedback about HAL, you can message the HAL-discuss mailing list.

Contributing

If you think some part of the spec needs changing, just fork this repo and raise a pull request with your changes.

Code/Libraries

hal_specification.md contains a list of libraries for working with HAL.

hal_specification's Issues

CURIE syntax issue

the CURIE spec https://www.w3.org/TR/curie/ says that CURIEs work by concatenating the prefix value and the value from the CURIE. the example from the draft http://docs.acme.com/relations/{rel} (using a URI template-ish syntax) makes it look as if i could embed the value somewhere, potentially not just using concatenation.
if the intent is to use CURIEs as defined, i suggest to remove the {ref} part and treat CURIE as specified as a prefix-only mechanism. if the intent is to support something more powerful, then CURIEs are not the right tool for the job.

remove https://katharsis.io/ from Java library list

The lib for https://katharsis.io/ doesn't point to any library associated with HAL appears to be someone's blog. Looks to be in Hebrew.

Any reason for having an underscore before "links" property ?

Not really important but why not just "links" without the underscore ?

FoxyCart is not HAL

By follow the link I found that FoxyCart is "partially REST", so it is not HAL. It also never mentioned that it is.

IANA spec reference is broken

The hal+json registration references http://stateless.co/hal+json which 404s.

@mikekelly could you setup a redirect from that to the correct URL?

Which I guess would either be:
https://tools.ietf.org/html/draft-kelly-json-hal-07
or
http://stateless.co/hal_specification.html

Add HALPresenter and ShafClient to Ruby Libraries

I've written two Ruby gems to work with HAL, which I think should be added to the Library wiki.

• HALPresenter (a serializer)
• ShafClient (a client)

And perhaps also a framework called Shaf which is used for building REST APIs. Those APIs uses HALPresenter and thus also the HAL mediatype.

Update JSON reference

the spec should be updated from using RFC 4627 to using RFC 7159 for referencing JSON.

Properties of Link entity

Hey there,
I currently work on implementing the HAL specification along side with an API I build for a customer. Digging through the documentation and specification I found the description of the Link enity as following:

Links
Links have:

A target (a URI)
A relation aka. 'rel' (the name of the link)
A few other optional properties to help with deprecation, content negotiation, etc.

What other optional properties are ment here? Could it be any type of additional property or are they defined somewhere else?

Best Regards!

ParkWhiz is not HAL

The linked documentation for ParkWhiz calls it REST and not HAL API. Also there is nothing like HAL in it.

Include Oat Ruby gem in library list

Hi.

I wrote the Oat gem a while ago as a media-type adapter layer that allows your code to declare resource properties at the message-level. Blog post and rationale here:

http://new-bamboo.co.uk/blog/2013/11/21/oat-explicit-media-type-serializers-in-ruby

It's being used and contributed to by a few devs, and bundles a HAL adapter.

In case you're interested in listing it.

Should _links only contain links with GET method ?

Say an api exposes blog posts and with each blog post, one would want to include a link to post comments, should that links be in _links ? or should there be some other property like _actions ?

XML examples

Could XML samples be provided along with the JSON examples? The specification says:

HAL provides a set of conventions for expressing hyperlinks in either JSON or XML.

But only JSON examples are given. I'd like to know how to express the same structures in XML.

Flask-HAL

Hey

We just released a Python Flask extension which implements the HAL specification. Would be cool if you could add to the wiki of libraries.

https://pypi.python.org/pypi/Flask-HAL

Thanks,

Chris

How to link two documents...

So the spec shows how links look in a response. What is the suggested way of linking two documents?

Is it still going forward with Link headers and a LINK HTTP method?

LINK: /user/1
Link: </user/2>; rel="best_friend", </user/3>; rel="boss"

and

UNLINK: /user/1
Link: </user/2>; rel="best_friend"

Or to just have a LINK HTTP method intake a LINK object as it is represented?:

LINK: /user/1
{
    "best_friend" : { "href": "/user/2" },
    "boss"        : { "href": "/user/3" }
}

and

UNLINK: /user/1
{ "best_friend" : { "href": "/user/2" } }

I would personally love to see #2 because it's simple and straightforward and matches it's represented state and clients don't need to worry about setting a header before the request and what not (KISS).

Of course on the application level, it would need to know how to resolve links if they want to have a literal (non-RESTful) connection between the two (MySQL FKs, MongoDB DBRefs, etc, etc)

There not very many resources on the net referencing the LINK action and how to go about doing it, however, there's a lot of talk about representing them in a response... Thus bringing confusion.

Anyway, which is right or proper?

support for out-of-line links

this is a duplicate of mikekelly/hal-rfc#17 (raised in support of dret/I-D#48), because i am not sure which of those two repos is the best one to address this question? if this one is, i'll happily close mikekelly/hal-rfc#17 and will start discussing the issue here.

Python package hal-json (LinkHeader) also implements this specification

Additional library that implements this specification:

python package: hal-json
https://github.com/inean/LinkHeader.git

Mime type?

Just wondering which mime type is preferred:

• application/hal+json: seen in this informal specification
• application/json+hal: seen in the ietf draft

Thanks!

http://stateless.co/hal_specification.html is throwing a 404

Could you please look into it, is there an alternative link we can use?

Custom link properties

I have a scenario where a "link" also requires additional data (eg. a background "texture" image, more of a visual flourish than semantic content), but otherwise conforms to being a link (that is, only the title and href are required).

What's the recommendation in this scenario? Can additional properties be added to links? If not, how is this type of data represented? It would seem odd to define a document/resource simply for this additional piece of metadata.

Audrey link is broken

It seems there is no service for the link

CURIE names for link relations

the spec should maybe have stronger wording about what a link relation's identifier really is. when a HAL document uses CURIEs, does that mean that all link relations (in embedded resources as well) MUST be interpreted as CURIEs and this effectively are URIs? that would make embedding HAL relatively brittle since the context then completely changes the interpretation of link relation values. what about overriding CURIEs in embedded HAL (possibly at multiple levels)? is that allowed and does it "black out" the CURIEs of the outer context? like any namespacing mechanism in nestable formats, these things get complicated and have nasty side-effects (the worst one being that interpreting HAL now is not context-independent anymore). the behavior around CURIEs probably needs more precise language and processing rules.

Let `_embedded` reference other items from the representation.

It would be nice if embedded resources could point to a location inside the current representation where the data lie.

Example:

instead of:

{
    "results": 2,
    "_embedded": {
        "foo:objects": {
            {"foo": "bar", "_links": {}},
            {"bar": "baz", "_links": {}},
        }  
    },
    "_links": {
        "curies": {
            "name": "foo",
            "href": "bar"
        }
    }
}

I would like to write:

{
    "results": 2,
    "objects": [
        {"foo": "bar", "_links": {}},
        {"bar": "baz", "_links": {}},
    ],
    "_embedded": {
        "foo:objects": $LINK_TO('/objects')$
    },
    "_links": {
        "curies": {
            "name": "foo",
            "href": "bar"
        }
    }
}

where $LINK_TO('/objects')$ should be some non-breaking idea. Maybe something like:

"_links": {
    "hal:embedded-ref": "/objects"
}

which would be a xpath / jsonpath expression.
:-( this would be a dependency on another library.
TODO / RFC: find a better idea

For me it would be enough to reference a top-level item.

• This would allow to define arbitrary JSON structures which are also compatible with e.g. an OpenAPI schema.
• This would flatten the structure of the document for e.g. readability (and non HAL consumers)
• This would allow to take a response payload and PUT it back as application/json without the need to transform it (just maybe dropping _links and _embedded).
• Tradeoff: This adds more logic to HAL clients and maybe a dependency on a xpath/jsonpath library
• This would separate contents from metadata. I interpret hypertext as the engine of application state in the way that the hypertext is just descriptive additional metadata not necessarily part of the response structure (well OK, in a HTML document you have the <form> somewhere mixed in the content).
• It would also ease the transition to HAL for existing applications as they only need to add _links + _embedded without transforming the prior content and therefor allow easier backwards compatibility (except for Content-Type: application/hal+json)

RFC link broken

On https://stateless.group/hal_specification.html, in the RFC section, http://tools.ietf.org/html/draft-kelly-json-hal is a broken link.

Perhaps the link should be https://tools.ietf.org/html/draft-kelly-json-hal-07 but I don’t know if that’s the current draft.

JSON example and hypertext cache pattern

Hi Mike,

I think there was a thread in hal-discuss about this but shouldn't the example in the main page have an ea:order within the links section? like so:

{
    "_links": {
        "self": { "href": "/orders" },
        "curies": [{ "name": "ea", "href": "http://example.com/docs/rels/{rel}", "templated": true }],
        "next": { "href": "/orders?page=2" },
        "ea:find": {
            "href": "/orders{?id}",
            "templated": true
        },
        "ea:admin": [{
            "href": "/admins/2",
            "title": "Fred"
        }, {
            "href": "/admins/5",
            "title": "Kate"
        }],
        "ea:order": [
           { "href": "/orders/123" },
           { "href": "/orders/124" }
        ]
    },
    "currentlyProcessing": 14,
    "shippedToday": 20,
    "_embedded": {
        "ea:order": [{
            "_links": {
                "self": { "href": "/orders/123" },
                "ea:basket": { "href": "/baskets/98712" },
                "ea:customer": { "href": "/customers/7809" }
            },
            "total": 30.00,
            "currency": "USD",
            "status": "shipped"
        }, {
            "_links": {
                "self": { "href": "/orders/124" },
                "ea:basket": { "href": "/baskets/97213" },
                "ea:customer": { "href": "/customers/12369" }
            },
            "total": 20.00,
            "currency": "USD",
            "status": "processing"
        }]
    }
}

According to the section about Hypertext cache pattern:

To activate this client behaviour for a given link, servers SHOULD
add an embedded resource into the representation with the same
relation.

Servers SHOULD NOT entirely "swap out" a link for an embedded
resource (or vice versa) because client support for this technique is
OPTIONAL.

This would imply that to have an embedded resource ea:order there SHOULD be a link ea:order which in this case would be an array of links, where each link points to a resource (which is what is being embedded).

If you agree I can make a pull request.

What is the proper media-type for HAL/JSON, especially in the context of wildcards and custom-media-types?

I have seen custom media-types that support HAL described as follows:

• application/vnd.application.entity.v1.hal+json
• application/vnd.application.entity.v1.json+hal
• application/vnd.application.entity.v1+hal+json

It seems like the second and third formats are illegal per section 4.2.8 of RFC6838 since it says that only registered suffixes should be used.

Another question I have is regarding the format for wildcard HAL. Which one of the following is correct?

• application/*.hal+json
• application/*hal+json

Based on the previously-mentioned RFC, I am assuming that application/*+hal+json is illegal as well.