mca blog

2012-03-04 Update:
there is a lively discussion in the comment section of Rob's blog post (the one referred in my content below). be sure to check it out.

this week Rob Conery issued an invitation to readers:

I would like to invite the good people who have engaged with me over the last few days to jump in and write me up an API.

he named some folks in paricular including Glenn Block, Kelly Sommers, Darrel Miller, Ian Cooper. and, even though i was not on "the list" i am offering up some possible examples anyway[grin].

turns out i had some free time during a commute last night and i took that time to whip up three possible interface examples. hopefully my contribution will spark some conversation and interest in the idea of designing Web APIs using in-message hypermedia instead of the common practice of limiting designs to mapping the problem domain directly to the HTTP protocol using URIs and protocol methods (more on that here).

WARINING: i did these in a bit of a hurry so there will be some minor problems, i suspect.

idle thoughts of a warped mind

i actually do these kinds of exercises quite often (almost daily). i see an application interface for the Web (a Web API, etc.) and my brain starts to sketch out how that might be done as a hypermedia interface. sometimes it's just data in my head. sometimes i scratch it out on loose paper, napkins, etc. that happen to by lying around. occassionaly, i pull up my handheld, laptop, etc. and pound out a doc for later. on a few occasions, i've even commited the design to disk w/ some scaffolding programming around it.

so, anyway, here are three possible hypermedia interfaces for the scenario Rob described in his blog post.

XML Hypermedia API

this is proly the easiest example to 'grok', the affordances are plain, the processing instructions pretty easy to apply to the elements. this is really a set of 'invented' hypermedia affordances w/o reference to a registered media type, but it still works fine. sticklers will want an actual MIME Type identifer for this and i'll claim application/vnd.conery+xml as the one i will use.

JSON Hypermedia API

this one is proly the hardest to 'grok' upon reading. the affordances here are for a little-used registered JSON hypermedia type ( application/vnd.collection+json which i designed myself about a year ago. it's similar to Atom, but in a JSON format that also includes support for ad hoc queries and a write template.

writing a client-side processor for this design is pretty straight-forward. i was able to build a quick one in JS and there is at least one in Java and Ruby, i think.

HTML Hypermedia API

using HTML as the API message base is really quite easy and has some key advantages. there is already a powerful processor client available (the common Web browser) and it's easy to "test" the API by just "surfing it" w/ a browser (thanks to Jon Moore for teaching me that phrase).

writing a processor for HTML Hypermedia means writing a client that is smart enough to recognize the semantic markers in the message (@id, @name, @rel, @class) and 'behave' accordingly at runtime; not too tough at all. i always output HTML APIs in valid XHTML so it's even easy for desktop/console apps to use XML processor tools to parse the messages first.

Oh, there's more...

I didn't come up w/ an example using Atom + AtomPub; that would be fairly easy, too. There is also HAL which is another solid hypermedia design. i've even toyed w/ implementing a hypermedia design for Markdown, YAML, or even CSV but haven't gotten around to sketching that stuff out.

So, there are some of my thoughts. how would you implement a REST API for Rob?