Re: [apps-discuss] JSON Hypertext Application Language

[Martin Thomson <[e-mail]>]

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.

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.

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.  There are better solutions; c.f. httpbis discussion on server
push.

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?

--Martin

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.