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

If locking of resources is truly a domain concern in your scenario then I would recommend modeling the lock as resource.

Here are some suggestions as to how you could do the requests you suggested.

GET /Triangle/Green/Count
GET /Triangle/Green/Available

POST /Item/Red/Large/Locks?quantity=200

DELETE /Item/21/Lock
DELETE /Item/23/Lock
DELETE /Item/25/Lock

POST /Square/Red?quantity=100

DELETE /Item/Green/Small?quantity=100

POST /Pentagon/Blue?url=/Pentagon/Yellow

Having said this, defining the URLs is somewhat irrelevant. Designing your media types with the appropriate link relations is the critical part of RESTful design.

Answer 2

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.

Answer 3

Read this for basic learnings... Me to stuck in What is REST...!!!

A content management system might contain a set of articles. There are implic- itly two resources here. First, there are the individual articles. Each consti- tutes a resource. There’s also a second resource: the collection of articles.

To fetch a list of all the articles, we could issue an HTTP GET request against this collection, say on the path /articles. To fetch the contents of an individual resource, we have to identify it. The Rails way would be to give its primary key value (that is, its id). Again we’d issue a GET request, this time against the URL /articles/1. So far, this is all looking quite familiar. But what happens when we want to add an article to our collection?

In non-RESTful applications, we’d probably invent some action with a verb phrase as a name: articles/add_article/1. In the world of REST, we’re not sup- posed to do this: we’re supposed to tell resources what to do using a standard set of verbs. To create a new article in our collection using REST, we’d use an HTTP POST request directed at the /articles path, with the post data containing the article to add. Yes, that’s the same path we used to get a list of articles: if you issue a GET to it, it responds with a list, and if you do a POST to it, it adds a new article to the collection.

Take this a step further. We’ve already seen you can retrieve the content of an article, issue a GET request against the path /articles/1. To update that article, you’d issue an HTTP PUT request against the same URL. And, to delete it, you could issue an HTTP DELETE request, again using the same URL.