What’s the best RESTful method to return total number of items in an object?

what'd
what meaning
what definition
what w
what does
what is called
how to pronounce what
what h

I’m developing a REST API service for a large social networking website I’m involved in. So far, it’s working great. I can issue GET, POST, PUT and DELETE requests to object URLs and affect my data. However, this data is paged (limited to 30 results at a time).

However, what would be the best RESTful way to get the total number of say, members, via my API?

Currently, I issue requests to a URL structure like the following:

  • /api/members—Returns a list of members (30 at a time as mentioned above)
  • /api/members/1—Affects a single member, depending on request method used

My question is: how would I then use a similar URL structure to get the total number of members in my application? Obviously requesting just the id field (similar to Facebook’s Graph API) and counting the results would be ineffective given only a slice of 30 results would only be returned.

While the response to /API/users is paged and returns only 30, records, there's nothing preventing you from including in the response also the total number of records, and other relevant info, like the page size, the page number/offset, etc.

The StackOverflow API is a good example of that same design. Here's the documentation for the Users method - https://api.stackexchange.com/docs/users

What, P!nk's official music video for 'So What'. Click to listen to P!nk on Spotify: http:// smarturl.it Duration: 3:46 Posted: Oct 25, 2009 WhatsApp works with Safari 9+ To use WhatsApp, update Safari or use Google Chrome, Mozilla Firefox or Opera.. Update Safari

I prefer using HTTP Headers for this kind of contextual information.

For total number of elements I use X-total-count header. For links to next, previous page etc. I use http Link header: http://www.w3.org/wiki/LinkHeader

Github does it same way: https://developer.github.com/v3/#pagination

In my opinion it's cleaner since it can be used also when you return content which doesn't support hyperlinks (i.e binaries, pictures).

P!nk - So What (Official Music Video), I will do what I can to help you. TranslationsEdit. show ▽what? (interrogative pronoun)� noun the true nature or identity of something, or the sum of its characteristics: a lecture on the whats and hows of crop rotation.

I have been doing some extensive research into this and other REST paging related questions lately and thought it constructive to add some of my findings here. I'm expanding the question a bit to include thoughts on paging as well as the count as they are intimitely related.

Headers

The paging metadata is included in the response in the form of response headers. The big benefit of this approach is that the response payload itself is just the actual data requestor was asking for. Making processing the response easier for clients that are not interested in the paging information.

There are a bunch of (standard and custom) headers used in the wild to return paging related information, including the total count.

X-Total-Count
X-Total-Count: 234

This is used in some APIs I found in the wild. There are also NPM packages for adding support for this header to e.g. Loopback. Some articles recommend setting this header as well.

It is often used in combination with the Link header, which is a pretty good solution for paging, but lacks the total count information.

Link
Link: </TheBook/chapter2>;
      rel="previous"; title*=UTF-8'de'letztes%20Kapitel,
      </TheBook/chapter4>;
      rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel

I feel, from reading a lot on this subject, that the general consensus is to use the Link header to provide paging links to clients using rel=next, rel=previous etc. The problem with this is that it lacks the information of how many total records there are, which is why many APIs combine this with the X-Total-Count header.

Alternatively, some APIs and e.g. the JsonApi standard, use the Link format, but add the information in a response envelope instead of to a header. This simplifies access to the metadata (and creates a place to add the total count information) at the expense of increasing complexity of accessing the actual data itself (by adding an envelope).

Content-Range
Content-Range: items 0-49/234

Promoted by a blog article named Range header, I choose you (for pagination)!. The author makes a strong case for using the Range and Content-Range headers for pagination. When we carefully read the RFC on these headers, we find that extending their meaning beyond ranges of bytes was actually anticipated by the RFC and is explicitly permitted. When used in the context of items instead of bytes, the Range header actually gives us a way to both request a certain range of items and indicate what range of the total result the response items relate to. This header also gives a great way to show the total count. And it is a true standard that mostly maps one-to-one to paging. It is also used in the wild.

Envelope

Many APIs, including the one from our favorite Q&A website use an envelope, a wrapper around the data that is used to add meta information about the data. Also, OData and JsonApi standards both use a response envelope.

The big downside to this (imho) is that processing the response data becomes more complex as the actual data has to be found somewhere in the envelope. Also there are many different formats for that envelope and you have to use the right one. It is telling that the response envelopes from OData and JsonApi are wildly different, with OData mixing in metadata at multiple points in the response.

Separate endpoint

I think this has been covered enough in the other answers. I did not investigate this much because I agree with the comments that this is confusing as you now have multiple types of endpoints. I think it's nicest if every endpoint represents a (collection of) resource(s).

Further thoughts

We don't only have to communicate the paging meta information related to the response, but also allow the client to request specific pages/ranges. It is interesting to also look at this aspect to end up with a coherent solution. Here too we can use headers (the Range header seems very suitable), or other mechanisms such as query parameters. Some people advocate treating pages of results as separate resources, which may make sense in some use cases (e.g. /books/231/pages/52. I ended up selecting a wild range of frequently used request parameters such as pagesize, page[size] and limit etc in addition to supporting the Range header (and as request parameter as well).

what, Quickly send and receive WhatsApp messages right from your computer. what definition: 1. used to ask for information about people or things: 2. used in questions that show you are…. Learn more.

Alternative when you don't need actual items

Franci Penov's answer is certainly the best way to go so you always return items along with all additional metadata about your entities being requested. That's the way it should be done.

but sometimes returning all data doesn't make sense, because you may not need them at all. Maybe all you need is that metadata about your requested resource. Like total count or number of pages or something else. In such case you can always have URL query tell your service not to return items but rather just metadata like:

/api/members?metaonly=true
/api/members?includeitems=0

or something similar...

WhatsApp Web, what definition: 1. used to ask for information about people or things: 2. used in questions that show you are…. Learn more. whatever: adverb at all , of any description , of any kind or sort , whatsoever , whichever

You could return the count as a custom HTTP header in response to a HEAD request. This way, if a client only wants the count, you don't need to return the actual list, and there's no need for an additional URL.

(Or, if you're in a controlled environment from endpoint to endpoint, you could use a custom HTTP verb such as COUNT.)

WHAT, Before you work yourself into a frenzy, take a moment to assess what's really going on and identify what's causing the strain in your relationship� The ORIGINAL and OFFICIAL "What What (In the Butt)" video! Samwell will CALL your friends and family! Go here: http://officialsamwell.com/live-call/ This is

What to Do If Your Boss Doesn't Like You, U.S. law requires employers to create a workplace free from discrimination and harassment. But as offices go virtual, what happens when staff� WhatsApp Messenger: More than 2 billion people in over 180 countries use WhatsApp to stay in touch with friends and family, anytime and anywhere. WhatsApp is free and offers simple, secure, reliable messaging and calling, available on phones all over the world.

What to Do When Your Employee Is Harassed Online, It is plural if a plural noun or noun phrase completes the sentence, as in He sometimes makes what seem to be gestures of reconciliation. � Clauses with what as� Seen a font in use and want to know what it is? Upload an image to WhatTheFont to find the closest matches in our database.

What, Search the world's information, including webpages, images, videos and more. Google has many special features to help you find exactly what you're looking for.

Comments
  • possible duplicate of Getting a count of returns seen by a RESTful request
  • +1: Definitely the most RESTful thing to do if fetch limits are going to be imposed at all.
  • @bzim You would know there is a next page to fetch because there is a link with rel="next".
  • @Donal the "next" rel is registered with IANA iana.org/assignments/link-relations/link-relations.txt
  • @Darrel - yes, it could be done with any type of "next" flag in the payload. I just feel that having the total count of the collection items in the response is valuable by itself and works as a "next" flag just the same.
  • To return an object that is not a list of item is not a proper implementation of a REST API but REST does not provide any way to get partial list of results. So to respect that, I think we should use headers to transmit other informations like total, next page token and previous page token. I never tried it and I need advice from other developers.
  • RFC6648 deprecates the convention of prefixing the names of unstandardized parameters with the string X-.
  • I was particularly interested in Range header, however I couldn't find enough evidence that using anything apart from bytes as a range type, is valid.
  • I think the clearest evidence can be found in section 14.5 of the RFC: acceptable-ranges = 1#range-unit | "none" I think this formulation explicitly leaves room for other range units than bytes, though the spec itself only defines bytes.
  • Embedding this information in headers has the advantage that you can make a HEAD request to just get the count.