I was recently looking on the web for a very clear description of what a RESTful resource is. Clear and accurate definitions were few and far between, so I decided I’d write one.
What Is a Resource?
A resource is:
- a noun
- that is unique
- and can be represented as data
- and has at least one URI
Examples of resources:
- today’s weather at US zip code 02138
- the English Wikipedia page about Dudeism
- the NPR article about the first page on the web
- the view from the Seattle Space Needle
- the Boston Ruby Group’s calendar
A Resource Is a Noun
This is a key aspect of RESTful architecture. URIs refer to nouns, not commands. For example, the current weather at zip code 02138 is represented by this URI on weather.com:
And by this URI on wunderground.com:
Note that weather.com’s URI is expressed as a noun, “weather”, with today and 02138 acting as adjectives further describing the noun. The URI from wunderground.com is expressed as verbs: “find weather” and “get forecast”.
Because weather.com’s URI is expressed as a noun, it points to a resource. Because wunderground.com’s URI is expressed as a verb, it does not point to a resource. Another way to say this is that wunderground.com’s web architecture is not resource-oriented.
A Resource Is UniqueThese are not resources because they are not unique:
- a rug
These are resources because they are unique:
- the deluxe Persian rug for sale by Rugs-a-Billion on amazon.com
- the article in the Boston Globe about how much milk we really need
- the faculty web page for Mr. Hudgins, my fourth grade teacher who introduced me to programming
The reason that resources need to be specific and unique is that the web is all about hooking things up. Only specific, unique things can be given a URI and hooked up to the web.
A Resource Can Be Represented As Data
Courage is a unique concept but it is not a resource because it cannot be represented as data. If a group of nihilists burns your car and confronts you in a bowling alley parking lot, you can’t simply download courage from the web. You can, however, download the definition of courage from dictionary.com, which is a resource.
A Resource Has At Least One URI
To quote chapter four of RESTful Web Services:
What makes a resource a resource? It has to have at least one URI. The URI is the name and address of a resource. If a piece of information doesn’t have a URI, it’s not a resource…
A URI can only point to one resource, but a resource can have more than one URI. For example, the current weather in Cambridge could have more than one URI:
Multiple Resources Can Point to the Same Data
It’s possible for different resources to have the same representation. For example, these two resources could return the same data:
- a description of the Wye Oak
- a description of the most famous tree in Maryland
Note that since the resources are conceptually different, at some point in the future another tree can become more famous than the Wye Oak and the two resources would then return different data.
To really understand resources and RESTful architecture, I would recommend reading:
- chapter five of Roy Fielding’s dissertation on REST because it is the authoritative source and
- O’Reilly’s RESTful Web Services which is very thorough.