Unclear scope of recommendation against total count remark

[scop]

https://github.com/zalando/restful-api-guidelines/blob/4d7b9d0ffd2ff65bd0ad5252c367aa49beac4dae/chapters/pagination.adoc#should-use-pagination-links-where-applicable

The "You should avoid providing a total count..." remark in that section can arguably be thought to apply to the whole concept of pagination instead of just the "SHOULD use pagination links where applicable" one where it is structurally located.

Would it be possible to clarify the intent somehow? For example, by moving it to the "MUST support pagination" section it would be clearer that it applies to all of the chapter's alternative pagination approaches, or by amending the remark with a few words like "You should avoid providing a total count along with pagination links unless there is a clear need to do so." would make it clear that it applies to this particular section only.

[ePaul]

(This is about rule 161.)

I agree, the remark doesn't really fit there. I see these options:

• move it to MUST support pagination
  • this way it's seen by everyone who looks at pagination at all
• move it to SHOULD use pagination response page object
  • but then it seems to just be applicable when that response object is used.
• create a new rule for this
  • but that seems like a too detailed rule, and might put too much emphasis on it.

Other options suggested by @tkrop:

• Add rule "avoid costly operations in pagination", which then includes the total count, but also says that offset-based pagination gets slower with larger totals.
• rewrite rule 160 to include this.

[ePaul]

In the guild meeting, we got to the conclusion that it makes sense to make it a separate rule, as we got some examples where APIs waste a lot of resources by including a total when it's not needed.

When a total is needed, of course it should be implemented (maybe as a separate resource, or with a query parameter requesting it).

@tkrop will open a PR for this.

[scop]

Thanks for looking into this!

(Edit: deleted some questioning which I see was due to myself just having read just a fraction of the fix.)