What, Exactly, Is a RESTful Resource?

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:

  1. a noun
  2. that is unique
  3. and can be represented as data
  4. and has at least one URI

Examples of resources:

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:

http://www.weather.com/weather/today/02138

And by this URI on wunderground.com:

http://www.wunderground.com/cgi-bin/findweather/getForecast?query=02138

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 Unique

Walter from The Big Lebowski

Those URIs really tied the web together, did they not?

These are not resources because they are not unique:

  • a rug
  • milk
  • teachers

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:

  • http://www.weather.com/weather/today/02138
  • http://www.weather.com/weather?zipcode=02138

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.

Further Reading

To really understand resources and RESTful architecture, I would recommend reading:

You can skip to the end and leave a response. Pinging is currently not allowed.

Leave a Reply