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

by

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).

More Related Contents:

  1. When do I use path params vs. query params in a RESTful API?
  2. How to create REST URLs without verbs?
  3. Jersey with Struts2 [duplicate]
  4. RESTful – What should a DELETE response body contain
  5. Hyphen, underscore, or camelCase as word delimiter in URIs?
  6. 400 BAD request HTTP error code meaning?
  7. How to design RESTful search/filtering? [closed]
  8. What are best practices for REST nested resources?
  9. How can I handle many-to-many relationships in a RESTful API?
  10. 400 vs 422 response to POST of data
  11. Pagination in a REST web application
  12. How to version REST URIs
  13. XDebug and RESTful server using PHPStorm or POSTman
  14. REST Complex/Composite/Nested Resources [closed]
  15. What is the advantage of using REST instead of non-REST HTTP?
  16. What is REST? Slightly confused [closed]
  17. powershell invoke-restmethod multipart/form-data
  18. Transactions across REST microservices?
  19. Designing URI for current logged in user in REST applications
  20. RESTful Services – WSDL Equivalent
  21. Making a PowerShell POST request if a body param starts with ‘@’
  22. How to use object filter with softlayer rest api?
  23. Does Karate DSL Framework have the capability to pass a POST Request as a url encoded format?
  24. Difference between Swagger & HATEOAS
  25. Flutter fetched Japanese character from server decoded wrong
  26. VSTS use API to set build parameters at queue time
  27. Can I change the headers of the HTTP request sent by the browser?
  28. When in my REST API should I use an envelope? If I use it in one place, should I always use it?
  29. Swagger UI passing authentication token to API call in header
  30. REST API DESIGN – Getting a resource through REST with different parameters but same url pattern

Leave a Comment