API results pagination is a bit of a trigger issue for me. It’s such an easy concept to conceptualize but is literally an exercise in edge cases. Part of the problem is the name itself, pagination, which evokes the image of advancing, sheet by sheet, through a printed document. What could be easier? Flip a page to move forward, flip a page to move back. Easy peasy. Accept that’s almost never what API pagination is, it’s usually a flexibly defined cursor moving through an asynchronously changing dataset, oh and via a stateless protocol.
So pagination isn’t like flipping pages through a printed document because:
- The concept of a page is dynamic.
- The document is likely changing under your feet.
- You’re trying to offer a stateful interface statelessly.
Dealing With It
So now that I’ve vented, and maybe even scared a few people, let me offer some practical advice because pagination is unavoidable.
The First Rule of Pagination…
I’m going to paraphrase the movie Fight Club, and say:
The first rule of pagination is: don’t offer pagination.
Obviously, that’s not realistic, but here are some practical takeaways:
- Don’t gratuitously add pagination…
