mca blog

representin'

Tue, 29 May 2012 20:48:00 GMT

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?

a great WS-REST 2012 @ WWW2012

Sat, 21 Apr 2012 09:44:00 GMT

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.

Whisky Web was great

Sun, 15 Apr 2012 09:55:00 GMT

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.

tangible REST

Tue, 06 Mar 2012 12:43:00 GMT

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?

Rob Conery's API Invitation

Sat, 03 Mar 2012 17:37:00 GMT

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?

template for node work

Fri, 02 Mar 2012 17:52:00 GMT

starting to ramp up my node-er-ing and have settled into some personal habits/standards that help me get past the 'dross' and into the heart of the puzzles.

so, i'll drop some of these items here in the blog as a way to 'out' my habits, get some feedback and refine my standards over time.

basic template for app.js

here's how i "start" my scripts:

/* hello, node */

// declare module to use
var http = require('http');

// handle all requests
function handler(req, res) {
  res.writeHead(200, 'OK',{'Content-Type':'text/plain'});
  res.end('Hello, node!  from '+ req.url);
}

// listen for requests
http.createServer(handler).listen(process.env.PORT);

a three-part model:

pull in requires
set up listener to run "handler" when the event fires (at the bottom)
supply the "handler" (as the actual function name)

some additional decoration

for non-trivial examples, i usually declare a module-level hash table (the use of the hash is a sanity check for my mental REPL when trying to resolve scope).

i also write a main(); to hold the routing logic or other high-level stuff. this is not needed, but again, keeps the code clean and sectioned off.

/* hello form */

// modules
var http = require('http');
var querystring = require('querystring');

function handler(req, res) {

  var g = {};
  g.url = '/';
  g.textHtml = {'Content-Type':'text/html'};
  g.form = '<h1>hello, form!</h1>'
    + '<form method="post" action="/" >'
    + '<label>Email: </label>'
    + '<input name="email" type="email" value="" placeholder="user@example.org" required="true" />'
    + '<input type="submit" />'
    + '</form>';
  g.output = '<h1>hello, form!</h1>'
    + '<p>{@email}</p>'
    + '<p><a href="/">return</a></p>'

  main();

  function main() {
    if(req.url === g.url) {
      switch(req.method) {
      case 'GET':
        handleGet();
        break;
      case 'POST':
        handlePost();
        break;
      default:
        sendResponse(405, 'Method not allowed', '<h1>405 - Method not allowed</h1>');
      }
    }
    else {
      sendResponse(404, 'Not found', '<h1>404 - Not found</h1>');
    }
  }

  function handleGet() {
    sendResponse(200, 'OK', g.form);
  }

  function handlePost() {
    var body = '';

    req.on('data', function(chunk) {
      body += chunk.toString();
    });

    req.on('end', function() {
      var results = querystring.parse(body);
      sendResponse(200, 'OK', g.output.replace('{@email}',results.email));
    });
  }

  function sendResponse(status, text, body) {
    res.writeHead(status, text, g.textHtml);
    res.end(body);
  }

}

http.createServer(handler).listen(process.env.PORT);

comments, suggestions, warnings?

any feedback you wish to share?

POST-PUT-PATCH illustrated

Thu, 01 Mar 2012 17:04:00 GMT

the announcement that Rails is adding support for PATCH has caused some gum-flapping on the Inter-Tubes and this all came up in a recent convo w/ some of my colleagues today. it turned out most of them don't have much experience in "talking HTTP" but know T-SQL really well. so i decided to illustrate the differences between HTTP's POST, PUT, and PATCH methods using simple T-SQL examples.

it seemed to resonate w/ the folks in the room so i decided to share it here. now, my T-SQL is a bit stilted, but it get ths point across.

hopefully, this illustration will spark some convos where you are and result in some deeper discussion and understanding of the HTTP protocol.

POST

HTTP.POST can be used when the client is sending data to the server and the server will decide the URI for the newly created resource.

"The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line."

this is what most of us think of when we talk about "creating data" on a web server. translating this into T-SQL is really easy; just use an auto-incrementing primary key for INSERTS.

-- T-SQL version of POST
CREATE TABLE [dbo].[PostToDo](
  [ID] [int] IDENTITY(1,1) NOT NULL,
  [Task] [nvarchar](1024) NOT NULL,
  [Completed] [nvarchar](10) NULL
) ON [PRIMARY]
 
-- Write ala POST
CREATE PROCEDURE WritePostToDo 
  @Task nvarchar(1024),
  @Completed nvarchar(10)
AS
BEGIN
  SET NOCOUNT ON;
  INSERT INTO PostToDo VALUES (@Task, @Completed)
END

-- Send some data
WritePostToDo 'Write code', 'no'
WritePostToDo 'Fix bugs', 'no'
WritePostToDo 'Deploy to production', 'no'
WritePostToDo 'Enjoy a beer', 'no'

-- Check out the results
SELECT * FROM PostToDo
1,'Write code', 'no'
2,'Fix bugs', 'no'
3,'Deploy to production', 'no'
4,'Enjoy a beer', 'no'

PUT

HTTP.PUT can be used when the client is sending data to the the server and the client is determining the URI for the newly created resource.

The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server. If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI.

yeah, so that's kinda dense but the basics are pretty clear:

client must supply the ID
if the resource exists, *replace* it with the inbound data
if it doesn't exist, create a new one (assuming you can do that)

so in T-SQL it just takes a bit more fiddling to determine if the record already exsits. if yes, do an UPDATE. if no, do an INSERT.

-- T-SQL vesrion of PUT
CREATE TABLE [dbo].[PutToDo](
    [ID] [int] NOT NULL,
    [Task] [nvarchar](1024) NOT NULL,
    [Completed] [nvarchar](10) NOT NULL
) ON [PRIMARY]

-- Write ala PUT
CREATE PROCEDURE WritePutToDo 
    @ID int,
  @Task nvarchar(1024),
  @Completed nvarchar(10)
AS
BEGIN
  SET NOCOUNT ON;

  IF(SELECT COUNT(*) FROM PutToDo WHERE ID=@ID)=0
    BEGIN
      INSERT INTO PutToDo VALUES (@ID, @Task, @Completed)
    END
  ELSE
    BEGIN
      UPDATE PutToDo
      SET Task=@Task, Completed=@Completed
      WHERE ID=@ID
    END
  --END IF
  
  SELECT * FROM PutToDo
END

-- Send some data
WritePutToDo 1, 'write code', 'no'
WritePutToDo 2, 'Fix bugs', 'no'
WritePutToDo 3, 'Deploy to production', 'no'
WritePutToDo 4, 'Enjoy a beer', 'no'

-- Check out the results
SELECT * FROM ToDo
1,'Write code', 'no'
2,'Fix bugs', 'no'
3,'Deploy to production', 'no'
4,'Enjoy a beer', 'no'

-- Send some more data
WritePutToDo 1,'write code','yes'

-- Check out the results
SELECT * FROM ToDo
1,'Write code', 'yes'
2,'Fix bugs', 'no'
3,'Deploy to production', 'no'
4,'Enjoy a beer', 'no'

PATCH

HTTP.PATCH can be used when the client is sending one or more changes to be applied by the the server.

The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the Request-URI. The set of changes is represented in a format called a "patch document"...

now we get to have some fun!

the spec clearly states this should involve a "patch document", not a typical resource write like in POST and PUT (interpret how you will...). anyway, the point is that PATCH is used to doing some kind of 'partial' update.

translating this into T-SQL is not too tough. i decided to use a 'patch document' that consists of four things:

ID of the record
the FIELD to patch
the OLDVALUE of the FIELD
the NEWVALUE of the FIELD

this allows the sproc to confirm that the field i want to modify has not already been modified by someone else since i last read in the data. that will cut down on problematic patches that might render the row invalid (again, interpret how you will...).

-- use the PutToDo Table definition

-- Write ala PATCH
CREATE PROCEDURE WritePatchToDo 
  @ID int,
  @Field nvarchar(50),
  @OldValue nvarchar(1024),
  @NewValue nvarchar(1024)
AS
BEGIN
  SET NOCOUNT ON;

  IF(SELECT COUNT(*) FROM PutToDo WHERE ID=@ID)!=0
    BEGIN
      IF(@Field='Task')
        BEGIN
          IF(SELECT Task from PutToDo WHERE ID=@ID)=@OldValue
            Update PutToDo
            SET Task=@NewValue
            WHERE ID=@ID
          --ENDIF
        END
      --ENDIF
      IF(@Field='Completed')
        BEGIN
          IF(SELECT Completed from PutToDo WHERE ID=@ID)=@OldValue
            Update PutToDo
            SET Completed=@NewValue
            WHERE ID=@ID
          --ENDIF
        END
      --ENDIF
    END
  --ENDIF
END

-- send some data 
WritePatchToDo 1, @Field='Task',
    @OldValue='write code',@NewValue='write buggy code'

-- Check out results
SELECT * FROM ToDo
1,'Write buggy code','yes'
2,'Fix bugs', 'no'
3,'Deploy to production', 'no'
4,'Enjoy a beer', 'no'

does that help?

hopefully, seeing HTTP concepts translated to another form helps folks get a handle on the differences between these HTTP methods. T-SQL made sense to the group i was talking to at the time. i wonder if there are other "translations" that would be helpful, too.

maybe you can show me?

essential node.js for web developers

Sun, 26 Feb 2012 20:29:00 GMT

i have the pleasure of presenting a talk at the CINNUG user group meeting Tuesday, February 28th. the title of my talk is "Essential Node.js for Web Developers" - one of my favorite topics of late!

Unlike some introductions that spend time explaining event loops and web sockets, this session start with a typical "Hello, Node" demo and quickly moves to short, fully-functional apps that show how to deal with static files, POST forms, mashups from other servers, file manipulation, data-handling, and even supporting HTTP Authentication.

If you need to get up-to-speed on Node.js really fast, or just want to get a great introduction to coding this powerful Web server, this talk is for you.

since a native version of node is now available on the Windows platform, node is poised to reach a wide audience and has the chance to make a big impact on the way we think about programming servers to support Web appliations.

if you're interested in seeing what it's like to "code with node", come to the CINNUG meeting this Tuesday and check it out.

entities and actions

Mon, 20 Feb 2012 10:24:00 GMT

those who read my blog know that i favor a hypermedia style when implementing dist-net apps. i don't always use that style (it's not always the proper style for the problem at hand), but when i have the chance to choose which style i implement, hypermedia is often my selection.

so that leads to an obvious question: "why?"

while there are many reasons (too many to cover here), there is one aspect of the hypermedia style that i enjoy very much: it's "action" orientation. not "event-driven" or "behavior-based" but "action" orientation.

problem domains

when working with clients, there is a point (usually early on) where the talk focuses on the "problem domain"; the stuff that must get done. often this information is "bottled up" within the heads of selected members in the client company; sometimes it's well documented in policies & and procedures documents. it can also appear as "source code" from some previous attempt at mapping the problem domain to computer code. this last method of expressing a problem domain is, IME, the least reliable as there have likely been several compromises (to fit the constraints of the coding environment) and often inaccurate translations (due to lack of understanding between the SME [subject matter expert] and the development team/person).

anyway, through some means, the domain is exposed sufficiently to allow the work of mapping that domain onto the selected technology stack. in my case, this is almost always some form of mapping the domain to services running over HTTP. that's what i do most often and, at this point, i rarely get "called" unless the client has "pre-selected" for an HTTP implementation anyway[grin].

so, the next step is how to go about mapping the domain to HTTP. this is not the same as writing code; this is before code. this is the design or architecture part of the experience. and, since it is a design process, there are lots of possibilities, lots of tools, lots of methodologies, etc. and few can be accurately labeled as clearly "right" or "wrong." at this point, this is mostly about the preferences, and proclivities of the architect/designer.

in my recent experience, there are two very common ways to approach this "mapping" task. one that focuses on the entities identified in the problem domain. another that focuses on the actions identified in the problem domain. there are other ways to view the domain (i.e. actors, components, etc.) but i'll focus on these two here: entites and actions.

action orientation

hypermedia designs focus on the actions taking place in the problem domain. things like "get a list of customers sorted by date" and "allow users to filter the order list by sales region" and "allow selected users to add new customers", etc. are all actions. when implementing a system using these actions as the centerpiece, hypermedia designs select the appropriate affordances (within the selected media type) and map those affordances to the identified actions.

for example:

"get a list of customers by date": <a href="..." rel="customers-by-date">Customers By Date</a>
"allow users to filter the orders list by sales region": <form action="..." method="get" class="filter-orders"> <input name="region" value=""/> </form>
"allow selected users to add new customers": <form action="..." method="post" class="add-customer">...</form>

in the above examples, the HTML.A and HTML.FORM affordances are used to provide the actions that map to the problem domain. note that hypermedia style implementations express the problem domain within messages themselves. this is an important point since it makes it possible to share this message in various ways and still retain the problem domain details (i.e. even if the message was sent via FTP, the affordances could still work and still retain their usefulness).

the use of in-message affordances to carry the semantic details of the problem domain (instead of mapping the domain directly to the network protocol) is sometimes cited as a drawback of the hypermedia style.

you'll notice that the actual URIs for each affordance are of little interest here. in the hypermedia style, URIs are treated as nothing more than transient identifiers that enable the actions. hypermedia style implementations are prepared for (and fully expect) the moment when the URI for an affordance changes (for any number of reasons). that is one of the reasons the hypermedia style expresses problem domain details via messages instead of URIs.

entity orientation

entity designs focus on the entities or objects within the problem domain. for example "customers", "orders", etc. are entities. when implementing systems focused on entities, the most common methodology is to create network identities (URIs) that contain the entity names (i.e. http://example.org/customers/, etc.). implementors then use the high-level transfer protocol's network methods as "operators" for each entity.

for example:

"get a list of customers by date": GET http://example.org/customers?order=date
"allow users to filter the orders list by sales region": GET http://example.org/orders?region=...
"allow selected users to add new customers": POST http://example.org/customers/

in the above examples, instead of using a message format to carry the domain semantics, entity oriented designs map the domain directly onto the available protocol and attempt to make URIs themselves carry meaning.

entity orientation is similar to RDF styles where the URI is treated as carrying intrinsic meaning and is the permanent identifier.

the appeal of this direct mapping of a problem domain to a network protocol is fairly obvious. it removes a layer of abstraction which exists for message-based hypermedia style. humans usually have little trouble mapping the limited set of HTTP protocol methods to simple operations on an "entity" (the classic Create, Read, Update, Delete === POST, GET, PUT, DELETE meme). finally, this entity view is easy to support via "tooling" since it essentially reduces distributed network interactions to passing internal objects around using only four possible operations.

but there are limits to this approach. first, entity orientation - while handy - is not how most humans think of life's interactions. usually they think first of the goal they want to achieve and then set up tasks in order to achieve it. second, it turns out to be quite difficult to get everyone to agree on the rules for forming identifiers. the HTTP world has experienced a decade-long dispute over how to handle permantent network identifiers and it still is not sufficently settled.

finally, it happens that many real world cases do not map well to the limited set of HTTP methods. usually there are some suggested compromises on how to handle certain operations within the problem domain (using HTTP.POST to send large search criteria, etc.). WebDAV solved this problem by adding seven additional HTTP methods that fit the targeted problem domain.

a matter of choice

in the end, it all boils down to choices. currently, implementing disitrubted network applications involves mapping the details of a problem domain to existing network standards. there is no getting around that; no choice there! but where we do have a choice is in how we go about accomplishing our task; the styles we use to map the domain to the standards. there are multiple ways to do this. i usually choose the hypermedia style since it tracks well with how i think about distributed networks, matches well with the existing strandards and technologies we use today ( URIs, HTTP, IANA) and presents very few restrictions when implementing clients and servers.

what implementation style do you use? and why do you prefer it?

A resource is not the thing...

Fri, 17 Feb 2012 11:43:00 GMT

this continues to be one of my favorite quotes from Roy Fielding. it captures not just some details about the HTTP protocol, not just the heart of the problem w/ attempts to use URIs as permanent identifiers, but also a fundamental observation of how humans actually operate in the world.

A resource is not the thing that is transferred across the wire or picked up off the disk or seen from afar while walking your dog. Each of those is only a representation. The same is true of physical objects encountered in life and never identified with URI and never made accessible on the net. Yes, it does present a bit of a quandary, but it is one that we have all learned to live with. Our eyes are not powerful enough to see identity through the representations, but our minds are powerful enough to associate identity to that which we see. Do I think of a different identifier every time I see my dog, or do I simply think of my dog as one identity and experience many representations of that identity over time (and on into memory and imagination)?

Roy Fielding - July 2002

this quote brings a smile to my face each time i read it.