News for hackers. Stuff that matters.
Re:Using HTML as the Media Type for your API by michaelsbradley on Wednesday July 11, 2012 @11:32AM (#4229668)
If you are concerned with having your API conform to HATEOAS, HTML offers some clear advantages over JSON. Namely, HTML has well defined "hypermedia affordances", or "H Factors"; plain old JSON has none:

H Factor

http://www.amundsen.com/hypermedia/hfactor/

Hypermedia-Oriented Design

http://amundsen.com/articles/hypermedia-oriented-design/

It's possible to develop and document a well-defined "semantic profile" for a hypermedia API that uses HTML as the base media type. For an example see:

ALPS - Application-Level Profile Semantics

http://amundsen.com/hypermedia/profiles/

By leveraging some or all of the details of the API, machine-to-machine logic can be developed fairly easily. In his recent book Building Hypermedia APIs with HTML5 and Node, Mike Amundsen demonstrates an example of a "microblogging bot" that consumes an API conforming to the semantic profile detailed in the ALPS document. The bot (written in JavaScript), knowing only the semantics involved with registration and "create post" links/forms, and an entry point for the API, is able to signup and begin making posts.

The interesting thing is that the precise implementation of the API is not important, e.g. whether it's written with NodeJS or PHP or Clojure or whatever. Also, from one implementation to another, the pages served by the API could vary in terms of the layout of the pages, CSS, etc. So long as the pages conform to the semantic profile, the bot should be able to work equally well with a wide variety of implementations.

Regarding JSON, there are a number of attempts to develop hypermedia-rich media types on top of it:

HAL

http://tools.ietf.org/html/draft-kelly-json-hal-03

JSON-LD

http://json-ld.org/

Collection+JSON

http://www.amundsen.com/media-types/collection/

Siren

https://github.com/kevinswiber/siren

There are others as well.

Re:Using HTML as the Media Type for your API by jon_moore on Wednesday July 11, 2012 @06:45PM (#4231862)
A lot of Mike Amundsen's work you've listed here is a direct inspiration for this article. Thanks, MCA!