mca blog

HTTP is the only application-level protocol I know of that relies on the concept of "representations" as the primary way to transfer information between parties.

discovery

i find myself repeating the above phrase relatively often lately. i noticed this aspect of HTTP many years ago. it greatly affected my thinking about the methodologies to employ when implementing solutions on the Web. once i grasped the notion that Web communications could exist at the abstraction of negotiable representations, a entirely new set of possiblities for improving the quality of communication were available to me.

but then...

realization

i quickly realized that most of the frameworks and other tooling at my disposal when building Web solutions ignores this level of abstraction. IOW, while i have easy access to private component objects and data elements and a well-established pattern for exposing these private objects to the public (Serialization), there are few common frameworks that make it easy to represent my private component details in one of the dozens of domain- and framework-agnostic registered media types designed for this very purpose.

that means, each time i want to craft a representation of my private object to share on the public Web, i need to "hand-roll" my representation layers. to me, while annoying, i assumed that this was the price i had to pay in order to maintain the SoC on the public Web that would allow me to safely interact w/ a wide range of clients and servers over time.

i also assumed others took the same POV; that they, too, felt this pain and would (eventually) prod frameworks and tool providers to "add-in" support for the representation-level abstraction.

but then...

discovery

it dawned on me (as i travelled around speaking, writing, and learning) that most devs i encountered didn't see things the same way i did. instead of "pining" for the SoC of representation abstractions, most devs simply accepted the status quo and assumed exposing private objects via serialization (and the perpetual wrestling match of keeping client object models and server object models in sync over time) was more than the norm, it was "the way to do things on the Web." in addition, to my chagrin, when i took the time to point out HTTP's representation abstraction most devs either denied it's usefulness and/or decried it's implementation details as too complex to be worth the effort.

few of those i spoke to even suggested that frameworks and tools should 'level up' and include proper support for the representation abstraction inherent in HTTP in order to remove these artifical barriers to improved communication options on the Web.

so...

realization

i concluded that it is important to continue to write about. and advocate for, increased support for representation abstraction in Web tooling. i am pleased to see evidence of increased use of representations in implementations, too (check the trending download count over time on the very solid mimeparse project). i'm happy to see popular frameworks adopting representation-as-a-pattern and it's good to see at least one framework adopting support for the representation abstraction.

but there is more work to be done...

discovery

as more people discover the power and possibility of representing domain-specific information in an implementation-agsnotic way, more Web solutions will exhibit the reusability, extensibility, and evolvability (among other things) that can result when implementing distributed solutions for the Web. IMO, the "new" trend of Web APIs will succeed (or fail) largely on the ability of tooling to support HTTP's representation abstraction.

realization

how well does your current set of frameworks and tools handle HTTP's representation abstraction?

i had the honor and pleasure of presenting my paper "APIs to Affordances: A new paradigm for services on the Web" (paper, slides) at this year's WS-REST Workshop as part of WWW 2012 in Lyon, France. i got some very good feedback during the review process and additional questions and comments at the workshop itself. it was great to be able to spend time with some of the very talented people working in the REST/HTTP Web services space.

papers

there were a number of very good papers presented. instead of singly any out, i'll just encourage everyone to follow the link and check them out yourself. i also know that some of the papers will be updated by the end of April 2012. be sure to come back and pick up the latest editions after that date, too.

more than one of the papers directly mentioned the issue of hypermedia transitions as part of the implementation/design of services on the Web. as my readers might expect, i find this encouraging. i've continued to work along lines that focus on moving past a read-only loosely-coupled Web toward a read-write Web while still maintaing a high degree of loose coupling. More than one paper showed specific work toward that aim. i look forward to the time when these kinds of implementations become not only common, but also as easily assumed as the notion of "a link" is today on the Web.

of course, hypermedia was not the only focus of the papers. there are several on general modeling of services on the Web as well as two papers on applying aspects of the Semantic Web to services on the Web.

connections

another of the highlights of this year's event was the chance to renew ties to several people i first met in person at the WWW 2010 in Raleigh, NC. i aldo got the opportunity to put faces to the names and twitter handles with which i'd been interacting over the last two years. having the time to talk w/ the attendees, presenters, and the workshop organizers (Rosa Alarcon, Cesare Pautasso, and Erik Wilde) is real 'boost' for me. it's a chance to hear new points of view, explore details, and gain an added appreciation for the work of others.

WWW 2012

and, yes, there was a full program of keynotes, sessiopns, and panels for the WWW 2012 event. i really enjoyed the keynotes this year; especially the talk by Neelie Kroes on the role of government in aiding the growth & safe-keeping of the Web. i also very much like the keynote by Bernard Stiegler on the "Age of Philosophical Engineering; view of how the Web is affecting all of us; even our brains.

all in all it was a good week; too bad it only happens once a year!

BTW - maybe i'll see you at WWW2013 in Rio.

this weekend, i had the great pleasure of participating in the innagural Whisky Web Conference in Edinburgh, Scotland. what a great event! Juozas (Joe) Kaziukenas organized the event and it lived up to the description on the front page of the web site:

A web conference created for the web community, by the web community, Whisky Web will have something to offer everyone who works with the web, be they a designer, a developer or something in between. This is an amazing opportunity to get your geek on in Scotland's inspiring capital.

There are great keynotes by Josh Holmes and David Zuelke as well as a fine list of talks by very engaging speakers. there was also a "Whisky Master Class" on the first evening presented by Craig Johnstone of Bruichladdich Distillery. four spirits to taste and lots of history and stories to go with them. Craig was quite entertaining.

NOTE
all the talks were recorded to video and should be available soon. i will post a link here when they are available.

in addition, the catering was solid and the venues were fantastic. the sessions were presented in The Hub at the top of the Royal Mile near Edinburgh Castle. the second day (the Hackathon) was hosted at the other end of the Royal Mile in a building called Our Dynamic Earth next to the Hollyrood Abbey. the facilites were excellent.

i had the honor to present an updated version of my Essential Node.js for Web Developers. it was a well-attended session and there were some very good questions and comments afterwards. i also must admit i dipped out of the proceedings to tour St Giles' Cathedral and to climb Calton Hill to take in a high view of the city of Edinburgh.

having ben involved (just a bit) in the "behind-the-scenes" of setting up and supporting a dev conference, i can say this effort was top notch all around. i am already setting plans for attending next year and encourage everyone to consider a trip to Edinburgh in spring of 2013 for some whisky and some web.

last week Rob Conery posted an invitation on his blog asking people to "...jump in and write me up a [RESTful] API." what followed was some lively discussion in the comment stream on that post and (to date) produced four sample API designs for Rob to consider.

that's pretty cool!

evidence of style

while each solution was different (they each reflect the designer's style), they are all evidence of attempts to provide a hypermedia-style solution to Rob's challenge. one of the things i like about all this is that it offers up tangible examples; not just theoretical discussion. since they are all actual examples, this also makes it possible to ask clear questions about what is shown; what is intended, why it exists, and what the expected results are for designing interfaces in this manner.

so, from my POV, the real value here is not just in the resulting designs, but also in the public process of offering up real attempts at solutions for a real problem.

we need more of this

i think we need to see much more of this, too. the more physical examples we have the more we can learn from each other, the more we can ask informed questions about style choices and, the more we can compare designs to tease out helpful commonalitiesand differences. what we also need (IMO) are running examples; live implementations that we can also inspect, compare, and evauluate. but i'll leave that topic for another blog post.

oh, BTW - thanks Rob!

now how 'bout some more folks offer Rob a sample API?

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?