1

When defining a resource orientated RESTful service do you think it's a good idea to define an explicit operation (verb) for querying data?

It seems obvious and easy to map CRUD operations on a resource orientated RESTful service using HTTP to operations such as PUT, GET, POST & DELETE but how should operations that query for multiple resources be mapped - using a new operation called 'QUERY' or still use 'GET' that returns a collection of resources.

I'm interested in people opinions and experience...

3 Answers 3

7

REST is about resources. What resource will your query return? A set of data? How is that set identified? How is it parameterized? This should determine the URL you would use with the GET operation:

GET /customers  would retrieve all customers
GET /customers?q=<query> would retrieve all customers matching the query

EDIT: The following not quite so clear to me

Thinking about the query as being about retrieving a resource which is a set of customers (for instance), I started to wonder about well-defined subsets of the set of all customers. Consider things like:

GET /customers/state/MA              Retrieve all customers in Massachusetts
GET /customers/country/UK            All in the UK
GET /customers/country/UK/postalcode/001-234    All in that postal code in the UK

Resources like these make sense to me as clearly identified resources, and not as queries. I'd continue to use a query string to retrieve an arbitrary set of customers, but where there is a natural partition of customers, I might indicate that in the URL space.

Recall that the GET operation is meant for idempotent operations, and is meant to promote caching. The response to these queries should permit some reasonable amount of caching (one day, perhaps). This would permit a client machine or proxy server to cache the result set for a period of time, saving server round trips.

5
  • to me this seems the obvious way of thinking about query for resources May 12, 2009 at 12:38
  • 1
    Let us know if that doesn't work out for you. I'm not a "fan" of REST, but thinking about the "R" in "REST" as "Resource" is the only way it makes any sense to me. May 12, 2009 at 12:41
  • do you prefer a more SOAP style of service? May 12, 2009 at 14:40
  • 1
    In general, yes. To me, services appropriate for the REST style are a small subset of all possible services. They're the ones that are service up resources. Anything else is not a nail, so the REST hammer should be left in the tool box. May 12, 2009 at 14:43
  • The problem is trying to map REST to a kind of Http based DAL. REST works much better if you think of it as a presentation layer instead. The only difference is that it is a presentation layer for a machine, not a human. You don't need to support arbitrary queries in a presentation layer. May 12, 2009 at 16:08
0

I would still use a GET and provide the parameters of the query in the URL.

0

Return a list of relevant resource URIs as the response.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.