2

Good practices for designing REST APIs say that one should use:

  • GET requests for the selection of an object (or a collection of objects)
  • POST requests for the creation of a new object

A pair of examples taken from here:

  • GET: https://example.org/api/v1/zoos selects all the zoos
  • POST: https://example.org/api/v1/zoos creates a new zoo

Now, all these methods are designed to either retrieve an instance (or a set of instances) or modify some instance status.

What about retrieving some statistics on those resources that are stored on the server (e.g., number of zoos stored on the server)? I would not expect something that requires me to download the entire collection and then count the number of documents. Still, I am not sure what should be the right syntax. Is the following:

https://example.org/api/v1/zoos/number

a proper way of doing it? If not, which is the best practice?

Eleanore
  • 1,750
  • 3
  • 16
  • 33
  • `https://example.org/api/v1/zoos/number` or `/count` seems fine, see http://stackoverflow.com/questions/3715981/whats-the-best-restful-method-to-return-total-number-of-items-in-an-object – Tim Jun 16 '14 at 14:24

1 Answers1

3

From my experience, REST APIs are usually segregated by {Resource}/{Action}/{Parameter}.

I recommend using:

/zoos/count

count tells me what you want to do with the zoos resource.

beautifulcoder
  • 10,832
  • 3
  • 19
  • 29
  • I agree with this approach – Tim Jun 16 '14 at 14:28
  • 2
    Be careful with the phrasing here. The URI is supposed to be a 'thing', not an action. AS such, perhaps `/Zoos/stats/count` would be better. `stats` would be like a meta resource of the `Zoos` resource and we are accessing the `count` resource in particular. There might also be something like `/Zoos/stats/last_update` or `/Zoos/stats/admin` etc. – thecoshman Jun 17 '14 at 12:58