Doc: How to properly use API pagination?

[Jeremy Davis]

I'm pretty sure that this is a shortcoming of the current documentation, although there is a chance that it's a bug.

I'm using Focalboard as a Mattermost plugin and have just recently started playing with the API.

It took me a while to get it going as the docs are a bit suboptimal (I want to complain, but I work in open source too and I get that there are only so many hours in the day).

FWIW these 2 issues are essential reading for getting started with the Focalboard Mattermost plugin API IMO:

• #1116
• #4420

Plus obviously the actual API docs:
https://htmlpreview.github.io/?https://github.com/mattermost/focalboard/blob/main/server/swagger/docs/html/index.html#api-Default-getCards

On face value it all appeared to be working well. Then I noticed that there were some cards missing! When I dug in a little deeper, I realised that it was only returning 100 results?!.

I note that the docs (at least for cards) show the suffixes ?page=56&per_page=56

So I tried checking with ?page=1 and that shows one of the missing cards, so on the right track. Then I tried with ?page=2 and got no results?! I also tried with ?page=0 and that just gave me the same 100 results I was getting initially (so I assume that with no suffix it defaults to ?page=0&per_page=100!?).

After a bit of trial and error, I ended up getting all the cards via a ?page=0&per_page=200 suffix (I have less than 200 cards). So whilst I'm now unstuck, I do have some remaining questions:

• Why does ?page=2 give no results?! Shouldn't whatever doesn't fit on page 1 spill over to page 2 and so on?
  • To answer my own question: Yes. page=0 is the first page of results, page=1 is the second page, page=2 returns no results as I have less than 200 cards!
• How do I ensure that I'm getting all cards (without just increasing per_page until it gives no extra results)? Is there a way to page through all results?
• And/or is there a way to force the API to return all results (i.e. turn off pagination)?