Re: HTML as a format for REST APIs

Hi David,

Thanks for taking the time to respond; further comments in-line below.

Le lundi 16 septembre 2013 à 08:57 -0400, David Janes a écrit :
> Sure. Here's how I see it (also see the comments and links to that
> original article you posted).
> 1) the underlying model is the important thing, not the serialization
> 
I partially agree with that (although at the end of the day, I believe
serialization plays a big role in effective adoption of a given
technology), but that's not particularly an argument one way or the
other :)

> 2) Machine to machine communications should use formats that are
> mostly written for that ... but still allow human readability. I.e.
> JSON.

The HTML-As-API camp is arguing the contrary, so this sounds more like
an opinion than a demonstrated fact. I think it's probably equivalent to
your next argument:
> 
> 3) HTML is a difficult to author correctly and a pig _to parse_ in
> practice, especially in constrained environments. I've got a ton of
> hands-on practical experience in my day job on this one (dealing with
> data transfer in the tourism industry) and it's difficult to get
> quality data in JSON and XML; when the source is HTML it's always a
> nightmare.

Yes, there is no question that JSON is much easier to write and to parse
than HTML; that being said, now that HTML5 defines a solid parsing
algorithm for parsing any HTML document, it's at least easier to parse
it reliably; but it is clear that it is also more resources-hungry.

> 
> 4) JSON won. API writers are using JSON, whether standards committees
> like it or not. 
> 
Clearly JSON has a lot of adoption in APIs; but so did XML 10 years ago;
at the end of the day, I think the format that wins is the one that
strikes the best cost/benefits ratio, and that ratio is rarely cast in
stone.

> 4a)
> JSON-LD has traction (e.g. Google), is relatively easy to overlay on
> ad-hoc JSON, is extensible almost by definitions and has an excellent
> reusable vocabulary (schema.org) specifically useful in the context of
> the IoT.

I agree JSON-LD provides an interesting evolution for adding semantics
and linking to JSON; but the schema.org vocabulary itself (and other
linked data vocabularies) is not restricted to JSON-LD, and is as
applicable to HTML through RDFa.

> 
> 5)
> Data is HTML is a trick, mainly useful when the _primary_ consumer is
> humans and the _secondary_ consumer is a machine (rather than the
> other way around).

I think that's reducing the potential role of HTML; among other things,
the capability of describing HTTP interfaces as HTML forms I started
this thread with gives an interesting feature to HTML that is not
inherently available to JSON or even JSON-LD.

>  I say this with 3 years of active participation in the Microformats
> community and being the lead author of the hAtom spec. That is
> entirely IMO but my feeling is that if data-in-HTML was the way to go,
> it would have been spontaneously widespread adopted by now.

Well, part of it as spontaneously widespread — a lot of what search
engines do is using HTML as a data format; but clearly it hasn't quite
gotten traction to the broader landscape of data formatting. I'm not
sure if it will, but again, this depends on whether that approach brings
more benefits or reduce more costs than other approaches do.

(FWIW, I'm not particularly sold on this approach; I'm mostly curious to
know whether people have investigated its applicability to Web of Things
scenarii)

Dom

Received on Monday, 16 September 2013 13:19:06 UTC