Clarify use of X-Total-Count

[dehora]

In "Could: Use Pagination Links Where Applicable", X-Total-Count is mentioned as an option for describing result count.

In JSON (which is the required media type), it's not necessary to ask clients to look in a header when a total count field can be added to the result entity, simplifying client access. The guidelines could be interpreted as saying when you serve pagination links, you are to use X-Total-Count in conjunction with paging links. It would be good to edit the example to include a total count in the data, and making X-Total-Count entirely optional. A final thought I guess is that we should consider avoiding custom headers to work with APIs unless they're strictly needed.

---

X-Total-Count seems to make most sense in these cases:

• The design style is to use the the Link header
• The response media type isn't able to carry the information
• The JSON response is an array instead of an object

The first two are not directly applicable (Link was removed a while back, we require JSON). The last one is (imho) something we shouldn't encourage because arrays don't afford extensibility the way object based collections/results can (eg you can't easily include pagination links with an array result in the example).

[ePaul]

I think you are right here. When we deprecated links in headers, we should have also deprecated this total count in headers.

Of course, when deciding whether to include such a total count at all in your API design, you should consider the performance implications (i.e. your database might need to have a look at all candidate items in order to count them, depending on filter criteria) and whether this information is actually needed.

[dehora]

Of course, when deciding whether to include such a total count at all in your API design,

Absolutely agree; I've seen this a number of times :) Perhaps it could be added as an aside to the guidelines.

[ePaul]

During the API Guild meeting we agreed this is a good idea.
@dehora, could you submit a pull request?