Is this RESTful?

Question

I have a Rails app that needs to expose values from a database as a web service - since I'm using Rails 2.x, I'm going with REST (or at least try). Assuming my resource is Bananas, for which I want to expose several sub-characteristics, consider this:

 - /banana          -> give a summary of the first 10 bananas, in full (all characteristics)
 - /banana/?name=<name>         -> give all characteristics for banana named <name>
 - /banana/?number=<number>         -> give all characteristics for banana number <number>
 - /banana/?name=<name>/peel          -> give peel data for banana named <name>
 - /banana/?number=<number>/length         -> give length data for banana number <number>

I don't want to search for ID, only name or number. And I have about 7 sub-characteristics to expose. Is this RESTful?

Thanks for any feedback!

Answer 1

What Wahnfrieden is talking about is something called Hypermedia as the Engine of Application State (HATEOAS) - a central constraint of REST as defined by Fielding.

In a nutshell, REST application clients never construct URIs themselves. Instead, they follow URIs provided by the application. So, URI templates such as the ones you're asking about are irrelevent at best. You can make them conform to a system if you'd like, but REST says nothing about how your URIs need to look. You could, if you wanted to, arrange it so that every resource in your system was available from http://example.com/{hash}.

Publishing URI templates, such as the ones you're talking about in your question, introduces tight coupling between your application and clients - something REST is trying to prevent.

The problem with understanding hypermedia-driven applications is that almost nobody implements or documents their "RESTful" systems this way.

It might help to think about the interaction between a human and server via a browser. The human only knows about content and links that the server provides through the browser. This is how a RESTful system should be built. If your resources aren't exposing links, they're probably not RESTful.

The advantage is that if you want to change your URI system, for example, to expose the Banana "Peel" attribute through a query parameter instead of a nested URL, you can do it anytime you'd like and no client code needs to be changed because they're not constructing links for themselves.

For an example of a system that embraces the hypertext-driven constraint in REST, check out the Sun Cloud API.