the importance of representations

2008-03-01 @ 22:24#

in my continued efforts to make sense of REST-compliant HTTP programming, i had a bit of a struggle grasping the importance of representations within the REST model. only after spending a good deal of time programming my own REST-compliant engine it completely made sense to me. and now i think 'representation-ally' whenever i am tasked with building and publishing an HTTP end-point. and that means thinking of the three basic layers of content abstraction:

  1. data store
    this is the actual data on the server. a typical example would be the "Employees" table in a relational database.
  2. resource
    this is a 'slice' or part of the data stored on the server. for example, one row from the "Employess" table would be a resource. a list of the employee names is another resource. another example would be the list of employees hired in the last 90 days. these are all resources.
  3. representation
    this is the actual content of the resource when it is presented to the client upon request. the most common format of a representation is (X)HTML (text/html). but there are many other formats such as XML (text/xml), JSON (application/json), Atom (application/atom+xml), etc.

the important thing here is to understand that there can be multiple representations of the same resource. you can have the JSON version of the employee name list; the XML version, the Atom version, etc. another key point about representations is that it is the job of the client (not the server) to select the appropriate resource. this is where most of the HTTP frameworks i see fall down. they do not allow clients to easily control the resource representations.

and how does a client tell the server which representation to return? the client sends the Accept header. and when the server honors that request, the server sends the Content-Type header with the reply. that is why the IANA list of standard mime types are so important. it is these mime types that are exchanged between client and server in order to make representations a reality.

and representations *are* a reality.

code