Designing robust and efficient RESTful APIs is crucial for any modern web application. A common challenge developers face is how to effectively communicate the total number of items available in a collection, especially when dealing with paginated results or large datasets. Understanding what’s the best RESTful method to return total number of items in an object goes beyond simple counting; it impacts API performance, scalability, and developer experience. This article delves into various approaches, evaluates their pros and cons, and recommends a widely accepted best practice to ensure your API remains both powerful and user-friendly.

The Challenge of Counting in RESTful API Design

When an API client requests a list of resources, such as /api/products or /api/users, they often need to know the total count of available items. This count is vital for implementing pagination controls, displaying statistics, or simply informing the user about the scope of their query. However, simply returning the full list can be inefficient, consuming excessive bandwidth and server resources, especially with thousands or millions of records. The core challenge lies in providing this essential metadata without compromising the performance or clarity of the API.

Many developers initially consider embedded counts within the response body. While straightforward, this can lead to unnecessary data transfer if the client only needs the count, or it can complicate the response structure, especially when dealing with deeply nested objects. Furthermore, fetching the entire collection to count items on the server side can be a costly operation, impacting response times. The goal is to find a method that is both efficient for the server and intuitive for the client, adhering to REST principles.

Consider an e-commerce application fetching a list of products. A user might filter by category or price range. If the API returns only a subset (e.g., 20 products per page), the client still needs to know that there are 345 total products matching the filter to build proper pagination links (e.g., “Page 1 of 18”). Without a clear and efficient way to retrieve this “total count,” API consumers might resort to less optimal methods, such as fetching all pages, which creates unnecessary load on the backend and increases latency for the end-user.

Common RESTful Approaches and Their Nuances

Developers have explored several methods for returning item counts in RESTful APIs, each with its own set of advantages and drawbacks regarding what’s the best RESTful method to return total number of items in an object. Understanding these approaches is key to making an informed decision for your API design.

One common, though often suboptimal, approach is to include the total count directly in the JSON response body. For example, a response might look like {"total": 345, "data": [...]}. While simple to implement and understand, this can bloat the response if the client only needs the data, and it couples the metadata directly with the primary data payload, which isn’t always ideal from a REST perspective focused on resource representation. Another variation involves using a dedicated endpoint, such as GET /api/products/count, which returns only a numerical value. This approach is clean and specific but requires an additional API call for every collection query, potentially increasing network overhead and round-trip times.

Another method involves leveraging HTTP methods like HEAD requests. A HEAD request is identical to a GET request, but the server sends back only the response headers and no body. Theoretically, a server could include the total count in a custom header on a HEAD request to /api/products. However, this is not widely adopted for count purposes because HEAD requests are primarily for retrieving metadata about a resource (like content type or last modified date) without transferring the full representation. Relying on it for a dynamic total count can be inconsistent with its intended use and might not be supported uniformly across all API gateways or client libraries. As noted by the Mozilla Developer Network, “The HEAD method asks for a response identical to that of a GET request, but without the response body.” MDN Web Docs on HEAD method.

Examining Query Parameters for Counting

Some APIs use query parameters to request a count alongside the data. For instance, GET /api/products?count=true might return the total count within the response body or a header. This combines the data and count request into a single call. While seemingly efficient, the server still needs to perform the count operation, which can be expensive. Moreover, the interpretation of count=true can vary, leading to inconsistencies if not clearly documented. For example, does it return only the count, or the count and the data?

• Pros of Query Parameters:
  • Single API call for both data and count.
  • Flexible, allowing clients to opt-in to count retrieval.
• Cons of Query Parameters:
  • Ambiguity in response structure if not strictly defined.
  • Server still incurs cost of counting, even if data is paginated.
  • Can deviate from standard REST resource representation.

The Recommended Approach: Using Response Headers with X-Total-Count

For what’s the best RESTful method to return total number of items in an object, especially in the context of paginated resource collections, the industry-standard and most robust approach involves using a custom HTTP response header, typically X-Total-Count. This method provides a clean separation of concerns, delivering essential metadata without polluting the response body or requiring additional network requests.

When a client makes a GET request to a resource collection (e.g., GET /api/products?page=1&limit=10), the API Question & Answer :

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

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.

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