How should I implement a COUNT verb in my RESTful web service?

rest http restapi
claymation picture claymation · Mar 22, 2011 · Viewed 14.3k times · Source

I've written a RESTful web service that supports the standard CRUD operations, and that can return a set of objects matching certain criteria (a SEARCH verb), but I'd like to add a higher-order COUNT verb, so clients can count the resources matching search criteria without having to fetch all of them.

A few options that occur to me:

  • Ignoring the HTTP specification and returning the object count in the response body of a HEAD request.

  • Duplicating the SEARCH verb's logic, but making a HEAD request instead of a GET request. The server then would encode the object count in a response header.

  • Defining a new HTTP method, COUNT, that returns the object count in the response body.

I'd prefer the API of the first approach, but I have to strike that option because it's non-compliant. The second approach seems most semantically correct, but the API isn't very convenient: clients will have to deal with response headers, when most of the time they want to be able to do something easy like response.count. So I'm leaning toward the third approach, but I'm concerned about the potential problems involved with defining a new HTTP method.

What would you do?

Answer

Yannick Loiseau picture Yannick Loiseau · Mar 22, 2011

The main purpose of rest is to define a set of resources that you interact with using well defined verbs. You must thus avoid to define your own verbs. The number of resources should be considered as a different resource, with its own uri that you can simply GET. For example: 

GET resources?crit1=val1&crit2=val2

returns the list of resources and

GET resources/count?crit1=val1&crit2=val2

Another option is to use the conneg: e.g. Accept: text/uri-list returns the resources list and Accept: text/plain returns only the count

Related questions

What is a good way to transfer binary data to a HTTP REST API service?

We are extending our HTTP REST API to allow clients to upload picture (for the purpose of this question, assuming binary data). So far we have only allowed simply strings in our API parameters. What is a good way to …

Read More
Which HTTP response code for "This email is already registered"?

I'm creating a RESTful API for creating users that enforces unique email addresses: Successful POST /users: HTTP 201 Created If I POST the same email address again, what should the response code be? Is 409 Conflict the appropriate response code?

Read More
How to expose a validation API in a RESTful way?

I'm generally a fan of RESTful API design, but I'm unsure of how to apply REST principles for a validation API. Suppose we have an API for querying and updating a user's profile info (name, email, username, password). We've deemed …

Read More