Re: [apps-discuss] JSON Hypertext Application Language

[Mike Kelly <[e-mail]>]

Hi Martin thanks for sharing your thoughts

The spec is a WIP and you can read the latest version here:
https://raw.github.com/mikekelly/hal-rfc/master/draft-kelly-json-hal-00.txt

further comments inline

On Fri, Jun 8, 2012 at 8:01 PM, Martin Thomson <[e-mail]> wrote:
> On 6 June 2012 18:50, Mike Kelly <[e-mail]> wrote:
>> http://www.ietf.org/id/draft-kelly-json-hal-00.txt
>>
>> Feedback welcome..
>
> Let's test that theory...
>
> I was initially inclined to call this an abomination, but that would
> require fairly strong substantiation.  Let's just go with unnecessary.
>
> Some colleagues gave me an overview of an API that uses something very
> much like this.  And aside from the initial aesthetic reaction, I have
> two complaints:
>
> - _links is almost useless
> - _embedded is an unnecessary optimization
>
> Let's first attack the concept of generic linking.  It didn't work for
> XML.  Reason: A user of a particular document needs to understand the
> semantics attached to a particular link in order to make sense of it
> and generic labels rarely work.

Technically, according to the Web Linking specification referenced a
link relation type should either be registered with IANA or a URI.
Exposing an HTML document describing the semantics of the link at its
URI provides an avenue for making sense of a link that clearly can
work. I've written a 'browser' for HAL which lets you surf a HAL API
and allows you to pull up documentation as-you-go for relations that
are URIs.

> For instance, I need to understand that a link labelled "fishCannery"
> leads to a resource that describes a fish cannery.  The value added by
> _links is limited to signaling to a generic application that the value
> of "fishCannery" is not just a string, but a URI.  In practice, none
> of the fields other than href are used.

There is value in that, it allows someone to build a generic link
traversal DSL which you could then apply out of the box to your app
like so:

follow the "fishCannery" link and then
  query the "search" link setting "fish" equal to "tuna"


> Now, the optimization.  Well, mostly, it's just an optimization.  The
> folks I was talking to who used it, used it because they wanted to
> save on HTTP requests (or they were using long polling and wanted to
> push multiple "events" at the same time).  They had decomposed their
> application into resources, then discovered that it was a little slow
> when you want to pull multiple linked resources because it added round
> trips.

Yes, this is exactly the purpose of _embedded. They are parts of a
representation that actually represent the state of some other,
related, resource rather. Data URIs in links are another way to
achieve something similar but (iirc) they have a size limit, and there
is the obvious issue of human-readability.

> There are better solutions; c.f. httpbis discussion on server
> push.

Don't know enough to comment, sounds dubious that HTTP can eliminate
need for embedding.

> In an HTTP context, embedding messes with caching, cannot be regarded
> as authoritative, and doesn't benefit from resource metadata.
>
> So, what's wrong with JSON?

It doesn't have these linking or embedding semantics. We have no
standard to build re-usable libraries and tooling around, this is an
attempt to establish a base standard without over-complicating the
issue.

> p.s. It should be application/<application-specific-name>+hal+json if
> you want to get super pedantic on media types, since hal is just
> another layer.  c.f. the profile link relation type for a discussion
> on why a media type (or subtype marking) might be unnecessary.

yes you could use a profile if you were so inclined. Personally, I am
happy to rely on a preceding relation to provide the context/meaning
of a given resource. I don't think this discussion is relevant here
though.

Cheers,
Mike