In response to my post about why it’s so hard for developers to understand REST, Alex Bunardzic talks about the importance of distinguishing resources and representations. I didn’t touch on the subject in my post, but Alex is right on the money that it’s a key distinction in REST that you must understand.

Dreaming of Chairs

If you read through the rest-discuss archives you’ll likely come to the same conclusion as Alex – many developers don’t understand the difference between resources and representations.

But what’s weird is the resource/representation distinction is a fundamental part of our spoken language and our understanding of the world. So we all understand the difference.

Think of a noun, let’s say a chair. We all have an idealized version of a chair in our minds – its something you sit on that usually has four legs, but not always. This idealized version of a chair is something that exists only in our minds. In REST terminology, its a resource.

Now if you look around you’ll see there’s an almost infinite number of ways that the idea of a chair can be translated into a real, actual chairs. Here are just a few examples:

Each of these real chairs is a representation of the chair resource.

We all understand the difference between the idea of a chair and real chairs, and thus between resources and representations. Therefore the only reason I can see why developers don’t see the distinction in REST is simply because they are stuck in the wrong frame of reference like I discussed yesterday.

Dreaming of Web Sites

Now let’s apply this distinction to the web. The W3C’s Architecture of the World Wide Web document has a great illustration showing the differences between identifiers, resources and representations.

The resource is a weather report for Oaxaca, Mexico. The resource only exists as a concept, you can’t touch it, you can’t feel it, its only in the mind of whoever created the Oaxaca weather report website. The website returns a representation of the weather report as an XHTML document, but it could also return an Atom feed, an image, etc.

Is This Important?

Is this really important – are resources really key to understanding REST? Let me quote an exchange on rest-discuss between Walden Mathews and Roy Fielding.

In modeling REST formally, you can remove “resource” from
the picture without harming the purely technical aspects of the
system. What you then end up with is a many-to-many relation
from URI to representations. Perhaps that’s all the Web *really*
is, but it’s hard to find any guidance in the building of useful
systems in that. Put another way, it’s hard to decide what value
such a system might be providing.

Walden Mathews

In response:

And that is the key, really, since the main reason we know that a conceptual resource must exist is because of the number of ways that a link can fail. It is only when people complain bitterly about the lack of an expected sameness that you realize the goal of the link has nothing to do with the listener at the end of the HTTP address, but rather the expectation that it identifies (indirectly, as there is no such thing as direct HTTP identification) something other than the address.

People don’t create links to server software; they create links to information.

Roy Fielding

Let me repeat. People don’t create links to server software; they create links to information. Service Oriented Architectures are about creating links to software. Resource Oriented Architectures are about creating links to information. Change your frame of reference.