how to specify a range of data or multiple entities in a restful web-service

Question

To access an instance of a User in a restful web-service the url is structured as shown in the curl request below:

curl -v -X GET -s "$BASE_URL/User/${customer_id}.json"

If I wanted to specify all User entities or page through a range of User entities, such as the first 50 Users in my database, how would I structure my request so that it is compliant with REST ???

Answer 1

You should start by trying to de-emphasize the meaning of the characters in a URI. While nice, pretty and readable URIs are a good thing, they have nothing to do with REST -- in fact it's a good exercise to judge the design of a RESTful interface by changing all the URIs to meaningless strings, and add the prettiness afterwards. A client should never have any knowledge of the server's URI structure, for the simple reason that the server won't be able to change it afterwards.

Next, if a list of customers is a meaningful concept to you, you should by all means turn it into a resource of its own right. In its representation, you might want to include some information about each individual customer, along with a link to each individual customer resource.

Paging? Good idea -- turn each page into its own resource, and link them together. Take a look at the way Google presents search results for a hint.

Often that's all you need because it's not necessary for the client to be able to specify the page size. But if it is, you essentially have two options: You can have a resource that encapsulates a form that allows you to specify the parameters that, when submitted, will directly or indirectly via a redirect take you to the appropriate URI. Or you can include a poor man's form, a URI template.

In any case, and to re-iterate my first point: Don't view a RESTful interface as an API that manifests itself as a set of URI construction rules. Instead, think of resources, representations, and hypermedia.