subbu.org

What is the best way to start building RESTful applications? One of the common advice heard is, "nouns are your resources". You walk through your application, identify all the nouns, model them as resources, and try to rely on HTTP verbs to operate on those resources. Use POST to create a resource, PUT to replace (or even create, when the client can name the resource), DELETE to delete the resource, and GET to get the resource. However, the notion that nouns can be used to identify resources is simplistic.

First of all, nouns should not be interpreted as what exists in some backend or what the application deals with behind the scenes. Take, for example, a web service that can return driving directions between two places. What are the nouns here? Not obvious. There won’t be direction resources stored in some database. What the web service wants to expose are collections of "direction"s computed based on some data/feeds/indexes. Each "direction" can be modeled as a resource, representing a starting point, distance along a path/road, and an end point. Similarly, take a search engine. What it deals with in the backend of search indexes, but what it exposes are collections of "result"s, where each result contains a URI and some metadata. In this case, each result can be modeled as a resource. These may be extreme cases, but it is critical to note that nouns are not what are dealt with in the system, but what are exposed through URIs to clients. So, the best way to identify resources is to look from the clients’ point of view.

If the web service ends up getting nouns wrong, the web service may find the set of HTTP verbs too limiting. It is also one of the complaints about REST that the set of verbs in HTTP is too small for all the complex operations that need to happen on resources. Take, for example, an web service managing user’s permissions in a social application. The web service wants to allow each user to allow/disallow sharing some information about the user with another entity or user. At first, "allow" and "block" seem like operations on a user or entity resource associated with a user. But these two operations don’t map to HTTP verbs. In this example, the resource is incorrectly identified. The resource needs to be identified as an association between a user and another user or entity, and each user can have zero or more such resources (i.e. a collection). Each resource has two states, i.e., "allow" and "deny". Let’s call this resource a "permission". Once this resource is identified, it is easy to operate on it via HTTP. The client would use POST to allow/deny a user/entity, GET to get all permissions or a specific permission, DELETE to delete an existing permission and so on.

Another challenge with nouns is determining their granularity. In general, finely grained resources make it easy to operate upon using HTTP verbs, while coarse grained resources make it hard. While there is no one-size-fits-all approach to help determine the granularity, one possibility is to think in terms of path segments of URIs, using the path segments to represent containment of collections of resources within other resources, and/or associations between resources. Take, e.g., a "person" resource. The representation of the person may include the person’s address book. If the web service models this as a single resource, it would be hard to manipulate the address book. Instead, if this is modeled as a "person" resource containing a collection of "address" resources, these resources can be managed in a more efficient manner.

Nouns can provide a good starting point for identifying resources, but as the above examples show, without refinements, it is not difficult to get it wrong!