Re: [apps-discuss] JSON Hypertext Application Language

[James M Snell <[e-mail]>]

On Fri, Jun 8, 2012 at 2:02 PM, Martin Thomson <[e-mail]> wrote:
>[snip]
> On 8 June 2012 12:36, Mike Kelly <[e-mail]> wrote:
>> 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.
>
> No question, HAL let's you walk the graph, but it takes a human being
> to make any sense of anything.  So, as I said, next to useless.
>[snip]

I think the most important consideration with this is: what will
developers *actually* do with the additional metadata vs. what they
*are able* to do. There is a distinct, and very practical difference.

Within the Atom format, when we defined the structure of a generic
link, we allowed for all kinds of additional metadata and that model
served as part of the basis for RFC 5988. And while the structure
allows for a great deal of potential use cases, the overall majority
of ACTUAL code focus solely on two attributes: the rel and the href.
Everything else tends to be ignored except in very specific
application cases. It's great that we can enable specific cases, but
we should not assume, necessarily, that a greater capacity for more
metadata is always a good thing.

Within the Activity Streams format (http://activitystrea.ms) there is
also working going on to define a basic mechanism for links within a
JSON Activity Stream. The mechanism I have proposed is very similar to
that seen in HAL except that it skips the object structure for a link
and just goes with Strings containing absolute IRI's. For example:

{
  "totalItems": 10,
  "links": {
    "next": "http://example.org?page=2",
    "previous": "http://example.org?page=1"
  },
  "items": [ ... ]
}

In this case, a developer is already going to have a reasonable
assumption as to what kind of resource the next and previous links
point to; and all the other metadata that is typically associated with
the generic link model simply is not necessary. An application that
understands how to process multi-paged activity streams following this
convention is going to know already to go looking for the next and
previous properties under link so there is no need at all (in this
case) for a "generic browser". The code necessary to support an
implementation of this is going to be very clear and concise.

It comes down to a tradeoff. Either we have a focused, concise,
efficient, minimal serialization that requires more application
specific handling or we have a generic, verbose, less-efficient
serialization that allows more generalized reasoning and browsing.
There are valid arguments for both, for certain, but I can see many
scenarios where HAL will just be way too verbose to be practical.

- James