[AndreasHae]

I‘m interested in the reasoning why API pagination is hard to add later, or rather what the benefit is of „leaving space“ in the API response while in reality returning all items at once.

Wouldn’t have to adapt the way the frontend consumes the API either way, keeping track of the current list state? Or is that what the author meant, that you should always write your list UIs as if they consumed a paginated API?

[michaelmior]

This is a narrow view, but one example is that if you're using JSON and your API response looks like this:

[{id: 1, …},…]

Then you can't easily add pagination without changing the structure of the response. Whereas if you have something like this:

{results: [{id: 1, …},…]}

then you can add in whatever other properties you need and this change can be made without immediately breaking any existing applications. Of course, it's still true that you'll have to rewrite the frontend to actually implement pagination, but it does do something for backward compatibility. You could probably still have old versions of the application at least display the first page of results without changes.

[jmull]

That's the best interpretation I could come up with as well.

I think the general idea is to leave room in distributed APIs to add metadata later. It's not really just about potential pagination, but leaving yourself a way to add/change functionality later without updating all the clients in lockstep with the server (always awkward and there's never a way to pull it off 100% cleanly).

[simonw]

Yeah, that's exactly what I was getting at here.

[tdeck]

In this case, it would often be better to make a breaking change than to have a client that thinks it's fetching all the items but isn't. For a frontend application sure, it might be fine that the user only sees one page, but it might also be a big problem. For backend APIs you absolutely don't want to add a new pagination mechanism that clients don't know about.

[justin_oaks]

I agree that the author wasn't quite clear on this point.

If you control both the client and the API, then pagination is something you can add in later. But setting up pagination early may make sense if the client isn't in your control.

The author gave the example of the an old mobile app that users don't update. The client is also out of your control if it's a public API that users call with whatever client code they choose.

That said, I'm not sure how setting up "fake" pagination is helpful if the client isn't already coded to use pagination responses from the server. So I'll have to assume the author means that any client you provide already has pagination logic built-in.

[eyelidlessness]

There are reasons not to return a bare array (eg they're executable JavaScript), but this one isn’t as strong IMO. It’s a tiny bit more work, one time, for clients to parse Link headers, but once done they’re an excellent way to convey pagination (and a whole lot of other neat metadata about related resources!). See, for example, GitHub’s API[1].

1: https://docs.github.com/en/rest/guides/traversing-with-pagin...