Understanding REST through an example

Question

My only real exposure to the ideas of REST has been through Ruby on Rails' RESTful routing. This has suited me well for the kind of CRUD-based applications I have built with Rails, but consequently my understanding of RESTfulness is somewhat limited.

---

Let's say we have a finite collection of Items, each of which has a unique ID, and a number of properties, such as colour, shape, and size (which might be undefined for some Items).

Items can be used by a client for a period of time, but each Item can only be used by one client at once. Access to Items is regulated by a server. Clients can request the temporary use of certain items from a server.

Usually, clients will only be interested in getting access to a number of Items with particular properties, rather than getting access to specific Items.

When a client requests use of a number of Items, the server responds with a list of IDs corresponding to the request, or with a response that says that the requested Items are not currently available or do not exist.

A client can make the following kinds of request:

• Tell me how many green triangle Items there are (in total/available).
• Give me use of 200 large red Items.
• I have finished with Items 21, 23, 23.
• Add 100 new red square Items.
• Delete 50 small green Items.
• Modify all big yellow pentagon Items to be blue.

---

The toy example above is like a resource allocation problem I have had to deal with recently. How should I go about thinking about it RESTfully?

Answer 1

The trick to understanding is to think about the problems from a focus on nouns instead of verbs.

In the rest world, the verbs are all "preset" and the nouns become infinitely flexible. In a soap or roc world, the verbs are infinitely flexible. Restrict your thinking to locking down the verbs and then see what nouns you need to solve your problem within the constraints you have.

That is exactly what darrel did in the answer above - he made up a new noun for a lock that would satisfy your constraints and then set up access to them to achieve what you wanted.

Some of your questions were search or filter related - for those think of GET against the types of resources, passing in query parameters to restrict or filter the results.