Table of contents
No headers

Resources and Representations

Last modified 00:20, 11 Mar 2011
Table of contents
No headers

Let's say you work in a company that has a database of clients, invoices and receipts.

Let's say you are asked who owes your company money. You might execute a query like:

SELECT
      clients.id, clients.name
FROM
      clients JOIN invoices
      ON clients.id = invoices.clientid
      JOIN receipts
      ON clients.id = recipts.clientid
WHERE
      SUM(invoices.amount) > SUM(receipts.amount)
GROUP BY
	clients.id, clients.name

You might then get a result like:

id name
28 It's In The Post Ltd.

Now what does that result row show you? Possible answers are:

  1. The sole client who currently owes you money.
  2. The result of the SQL query shown above.
  3. The number 28 followed by the string "It's In The Post Ltd."
  4. A string of the characters U+0032 DIGIT TWO, followed by U+0038 DIGIT EIGHT, followed by a string of the characters U+0048 LATIN CHARACTER I, followed by U+0074 LATIN…
  5. A record from the clients table of the database

All of the above are completely correct. As a programmer you may be concerned with any one of the later answers along with all manner of concerns about indices, file groups, encodings and so on.

The answer that your company actually cares about – which is the whole point of the exercise – is the first one.

Now, let's say you get asked this often enough so you write a script so that http://example.net/outstandingAccounts.php returns the following:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 
<html xml:lang="en" lang="en" xmlns="http://www.w3.org/1999/xhtml"> 
  <head> 
    <title>Outstanding Accounts</title> 
  </head> 
  <body> 
    <h1>Outstanding Accounts</h1> 
    <table> 
      <thead> 
        <tr> 
          <th scope="row" abbr="name">Company Name</th> 
        </tr> 
      </thead> 
      <tbody> 
        <tr> 
          <td>It's In The Post <abbr title="Limited Company">Ltd.</abbr></td> 
        </tr> 
      </tbody> 
    </table> 
  </body> 
</html> 

Now, we might ask the same question here, what is it we are looking at when we go to http://example.net/outstandingAccounts.php?

Possible answers are:

  1. The companies that owe you money.
  2. A table of the companies that owe you money.
  3. An HTML page that encodes a table of companies that owe you money.
  4. A PHP script that generates an HTML page that encodes a table of companies that owe you money.
  5. Some of the contents of the clients table in your database.

Again, all of these are correct, but only the first one is what we are ultimately interested in, though the others may concern you as a hacker.

This of course happens all the time in computing – we deal with 1s and 0s and a bunch of different higher-level constructs we've built on top of those 1s and 0s but the reason we are doing it is normally because we're interested in something we are using those 1s and 0s to represent; most often something that has nothing to do with computing itself.

On the web we call the things we're really interested in "resources", and it is the resource that the URI identifies There is some debate as to exactly what a resource is, particular as to whether the resource is the companies themselves, in this example, or the information we have on them.

In any case, the resource is not a bunch of 1s and 0s that come down the wire. The 1s and 0s (in this case, encoding an HTML page) we call a "representation". Representations include both the data sent (called an "entity") and the metadata in HTTP headers that go with it.

REpresentations are the RE in REST. These are Transferred (both the T in REST and the second T in HTTP) between client and server (server→client with GET, client→server with PUT and client→server→client with POST, though there can be a few exceptions such as a POST not receiving a representation back).

A representation reflects the State of the resources the client and server are concerned about, and the transfer affects the state of both, which is the S in REST.

Important Aspects of Resources and Representations.

Representations change with Time

Let's consider the case of our looking at http://example.net/outstandingAccounts.php a month later. Now we see the following:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 
<html xml:lang="en" lang="en" xmlns="http://www.w3.org/1999/xhtml"> 
  <head> 
    <title>Outstanding Accounts</title> 
  </head> 
  <body> 
    <h1>Outstanding Accounts</h1> 
    <table> 
      <thead> 
        <tr> 
          <th scope="row" abbr="name">Company Name</th> 
        </tr> 
      </thead> 
      <tbody> 
        <tr> 
          <td>It's In The Post <abbr title="Limited Company">Ltd.</abbr></td> 
        </tr> 
        <tr> 
          <td>Tardy &amp; <abbr title="Company">Co.</abbr></td> 
        </tr> 
      </tbody> 
    </table> 
  </body> 
</html> 

It's In The Post Ltd. still owe us money, and now so does Tardy & Co.

What's changed here?

The resource itself is still companies that owe us money. The state of companies that owe us money has changed and the representation has changed accordingly.

Multiple Representations may be Available for a Resoruce.

Our colleage François looks at http://example.net/outstandingAccounts.php

Unlike our browser that favours English, his favours French. Knowing that our Francophone colleague will be using this page we've coded our script so that it returns a French version to his browser, though the companies names are alas English:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 
<html xml:lang="fr" lang="fr" xmlns="http://www.w3.org/1999/xhtml"> 
  <head> 
    <title>Encours Impayés</title> 
  </head> 
  <body> 
    <h1>Encours Impayés</h1> 
    <table> 
      <thead> 
        <tr> 
          <th scope="row" abbr="nom"> Nom de Compagnie</th> 
        </tr> 
      </thead> 
      <tbody lang="en" xml:lang="en"> 
        <tr> 
          <td>It's In The Post <abbr title="Limited Company">Ltd.</abbr></td> 
        </tr> 
        <tr> 
          <td>Tardy &amp; <abbr title="Company">Co.</abbr></td> 
        </tr> 
      </tbody> 
    </table> 
  </body> 
</html> 

We have here a French representation of the same resource. The resource does not change according to whether it is being looked at by you or François, but the representation returned does.

To quote from Dr. Fielding's dissertation:

More precisely, a resource R is a temporally varying membership function MR(t), which for time t maps to a set of entities, or values, which are equivalent.

The membership of a representation may be static (due to IETF rules about RFCs being immutable once published we can expect to find the exact same representation returned by http://www.ietf.org/rfc/rfc2616.txt in ten years time as now) or it may change with every single request. The number of available representations at any one time may be 1 (two of the three most common cases – a URI served by a single flat file or by a script which does not vary its output based on anything other than the core data it works from), it may be 0 (e.g. if you put a link in the above file to <a href="noDebts.php" >Clients with cleared accounts</a> but haven't yet written a script to deal with that then there is a resource, but not yet any representations) or it can be boundless.

Important cases

Resource Identity

Let's consider two URIs, http://example.net/a and http://example.net/b. Do they point to the same resource?

If they both return the same representation are they the same? Not necessarily.

Consider:

http://example.net/importantDoc/current and http://example.net/imporantDoc/version2.3. Most likely the intention is that the latter will never change, but the former will. While version2.3 is the current document you will get the same representation from both (whether directly from both, or by the former URI redirecting you to the latter) but when version2.4 is published this will no longer be the case. There is a relationship between these two resources, but they are not one and the same thing.

Alternatively, can we say that if the same representation is not returned that two resources are different?

Again no. A server will return a representation to us based on it's understanding of the state of the resource, it's understanding of which version we would prefer, and a whole host of implementation details.

The answer to how we know two resources are the same is "someone tells us so".

In HTTP, arguably (some disagree) receiving a 301 Moved Permanently redirect means two resources are the same. There's some disagreement on whether this is really the case though all agree that the other redirects do *not* mean this.

RDF (a grammar for talking about resources) and OWL (a vocabulary that can be used in RDF for talking about relationships between resources) can be used to say:

 <rdf:Description rdr:resource="http://example.net/a"> 
  <owl:sameAs rdf:resource="http://example.net/b"/> 
</rdf:Descriptions> 

Or more simply HTML can be used to say

this resource is the same as <a href="/b">this one</a>.

Two cases were we care about this is browser histories (and visited link colours based on them) and caching. In both these cases we need to know "is this resource the same as one I saw before?". Most of the time the answer is "only if they have *exactly* the same URI".

Representations as Resources

As we've explained above, a resource is not the same as the representation returned by a webserver, but rather the thing we are interested in when we went to the webserver. Resources can therefore be just about everything, and since "everything" includes representations, can a representation be a resource?

Yes, though it's relatively rare.

Think of a case where someone goes to the web and cares about the 1s and 0s more than what the 1s and 0s are about. Probably the only example would be when one is downloading a piece of binary code such as an installer for an application.

Interestingly, in this case while the resource does have a representation that is one and the same as itself, this does not mean it's the only representation possible. It could also, if queried by an RDF agent that only accepted application/rdf+xml an RDF description of itself.

Relationships between Resources

Some representations allow us to indicate relationships between resources. The media-types that allow a representation to do this are called hypertext or, more generally, hypermedia.

Consider the following:

 <html xml:lang="en" lang="en" xmlns="http://www.w3.org/1999/xhtml"> 
  <head> 
    <title>Outstanding Accounts</title> 
  </head> 
  <body> 
    <h1>Outstanding Accounts</h1> 
    <table> 
      <thead> 
        <tr> 
          <th scope="row" abbr="name">Company Name</th> 
        </tr> 
      </thead> 
      <tbody> 
        <tr> 
          <td><a href="http://restpatterns.org/company.php?id=28">It's In The Post <abbr title="Limited Company">Ltd.</abbr></a></td> 
        </tr> 
        <tr> 
          <td><a href="http://restpatterns.org/company.php?id=47">Tardy &amp; <abbr title="Company">Co.</a></abbr></td> 
        </tr> 
      </tbody> 
    </table> 
  </body> 
</html> 

Here we've added some links to two new resources, http://example.net/company.php?id=28 and http://example.net/company.php?id=47. These two resources are presumably the companies in question. Their representations would presumably return information about those companies.

Because there is links in the above HTML we know of a relationship between these three resources. Further, starting with the URI http://example.net/outstandingAccounts.php we can first obtain a representation of the outstanding accounts and then obtain a representation of each of the companies in question.

This is how hypermedia drives RESTful systems.

Another thing worth noting here is that both pages are presumably generated from the same PHP script; company.php

Despite the clues to this from the implementation artefacts in the URI we don't know this for sure though. http://example.net/company.php?id=28 and http://example.net/company.php?id=47 are completely different URIs. The most obvious implementation one can work out quickly, but that tells us nothing we can depend upon if we're writing code for the client side. All the choice of URI design does here is sacrifice prettiness for convenience.

Conversely, lets say the two URIs were:

http://example.net/clients/ItsInThePost and http://example.net/clients/TardyCo what do we know now?

Exactly the same as we did before. Indeed, these URIs could well be served by a server-side rewrite that turns them into the first two URIs before passing them to the PHP engine.

More to the point, what do we know about http://example.net/clients/ ?

Again, nothing. It *might* return a list of all clients or some other representation of the entirety of your client base. It might not. Now, it's handy to be able to guess at such things as a human browser but you can't be sure you'll be right until you try. That convenience is not a matter of how REST works. In REST if we want to say in http://example.net/clients/ItsInThePost that there is something at http://example.net/clients/ then we put a link in the representation to <a href="../">. No link, no hypertext, no known relationship.

Page statistics
14001 view(s) and 11 edit(s)
Social share
Share this page?

Tags

This page has no custom tags.
This page has no classifications.

Comments

You must to post a comment.

Attachments