representation abstraction

2008-03-20 @ 17:12#

for quite a while now, HTTP programming frameworks have been supporting the idea of mapping URI to classes and/or methods - usually via a routing list or table. when i designed exyus i decided to decorate the classes themselves with one or more URI templates. this elevates URI to a first-class element of the programming construct and eliminates the additional meta-data management by the programmer.

another decision i made was to limit the functions of the exyus base classes that talk to HTTP clients to Get(),Put(),Post(),Delete(),Options(). this means programmers are 'lead' into the garden of HTTP methods - no need to 'map' a function at all.

now that other folks are also thinking that programming HTTP means you can use a consistent set of functions in your classes, it's time to bring up another key element for treatment within HTTP programming engines - representation abstraction.

abstracting representations allows clients to indicate to the server (using the Accept header) the media-type they prefer when making a request for a resource using a URI. in other words, the server must be ready to render the resource in the format requested by the client. of course, the server is in charge of the list of supported media-types. if a client requests one that the server does not honor, the server should tell the client (using Not Acceptable 406).

supporting representations properly means the server needs to 'abstract' the media-type away from the resource. that means all the various formats used internally by the server; the storage format (relational db table); the internal data format used by the compiler (binary); even the format used internally to build the representation for the client (XML). none of these, necessarily, is the media-type sent to the client. for example, the client might request a JSON representation or an Atom representation.

the challenge for most HTTP programmers is that representation abstraction is not handled well in common tool kits. some offer no built-in support for representations. others offer the ability to sniff headers and then execute code branches. a few allow you to associate a method with a media-type. this eliminates the code branching, but forces developers to often duplicate code in order to support multiple media-types. the better approach (the one i took with exyus) is to mark the resource classes with the list of representations supported and use code within the functions to determine the proper representation and do the transformation as needed.

supporting loosely-coupled representations for HTTP resources is essential to building robust and flexible Web applications.