How should a REST URL schema look like for a tree hierarchy?

Question

Let's assume that I have stores, shelves in a store, and products on a shelf. So in order to get a list of products on a shelf in a store, I'd use the following request:

GET http://server/stores/123/shelves/456/products

From here, how would I get an individual product? Should I use:

GET http://server/products/789

Or:

GET http://server/stores/123/shelves/456/products/789

The first method is more concise, since once you get a list of products, you don't really care which store it belongs to if you just want to view the details for a particular product. However, the second method is more logical, since you're viewing the products for a specific shelf in a specific store.

Likewise, what about a PUT/DELETE operation?

DELETE http://server/stores/123/shelves/456/products/789

Or:

DELETE http://server/products/789

What would be the correct way of designing a schema for a tree hierarchy like this?

P.S. If I'm misunderstanding something about the REST architecture, please provide examples on how I can make this better. There's way too many people who love to say "REST is not CRUD" and "REST is not RPC", then provide absolutely no clarifications or examples of good RESTful design.

Answer 1

I've noted 2 approaches to RESTful URI design: hierarchical & filtered

I feel hierarchical is overly verbose, has the potential for redundant endpoints (not DRY) and disguises in what resource's state you're really interested (after all, REST = representational state transfer).

I favor Simple URIs

Simple is elegant. I'd choose a URI structure like

GET http://server/products/789

because I am interested in the state of the product resource.

If I wanted all products that belonged to a specific shelf at a specific store, then I would do

GET http://server/products?store=123&shelf=456

If I wanted to create a product at a specific store on a specific shelf then I'd post

{
    product: {
        store: 123,
        shelf: 456,
        name: "test product"
    }
}

via

POST http://server/products

Ultimately, it's tomayto, tomahto

REST doesn't require one over the other. However, in my own experience, it is more efficient to consume a RESTful API that maps single entities to single endpoints (eg: RestKit object mappings on iOS) instead of having an entity map to many different endpoints based on what parameters are passed.

About REST

As far as REST, it is not a protocol and has no RFC. It is tightly related to the HTTP/1.1 RFC as a way to implement its CRUD actions, but many software engineers will posit that REST does not depend on HTTP. I disagree and consider such as conjecture, because the original dissertation by UCI's Roy Fielding (http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm) explains the deep rooted connection of REST and HTTP/1.1. You may also enjoy Roy's opinion on the topic: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven.

The principles defined by REST can be applied to other protocols, but REST was built for the internet and HTTP is the protocol for the world wide web.

REST vs RPC

RPC is all about making calls to remote functions and is verb-centric.

REST is all about using the CRUD convention to act on data depending on how the CRUD operation applies to a given data type and is noun-centric.

You can accomplish the same things with REST or RPC, but REST follows DRY principles because for every URI you can perform 4 actions whereas RPC requires an endpoint for each action.

PS

Much of this is my opinion and based on my experiences, but I hope it sheds some light on how you could most efficiently design a RESTful URI schema. As always, your specific goals and needs will affect your choices, but simplicity is always a good target for which to aim.