REST api pagination: make page-size a parameter (configurable from outside)

Question

Hi guys,

we are having a search/list-resource:

http://xxxx/users/?page=1

Internally the page-size is static and returns 20 items. The user can move forward by increasing the page number. But to be more flexible we are now thinking also to expose the size of a page:

http://xxxx/users/?page=1&size=20

As such this is flexible as the client can now decide network-calls vs. size of response, when searching. Of course this has the drawback that the server could be hit hard either by accident or maliciosly on purpose: http://xxxx/users/?page=1&size=1000000

For robustness the solution could be to configure an upper limit of page size (e.g. 100) and when it is exceeded either represent an error response or a HTTP redirect to the URL with highest possible page-size parameter.

What do you think?

Answer 1

Managing access to resources is always a good idea aka protecting outside interfaces: in other words, put a sensible limit.

The redirect might be a good idea when it comes to development time i.e. when the user of the API gets acquainted with the service but outside of this situation, I doubt there is value.

Make sure the parameters are well documented either way.

Answer 2

Personally, I would simply document a maximum page size, and anything larger than that is simply treated as the maximum.

Answer 3

Have you tested this to see if it's even a concern? If a user asks for a page size of a million does that really cause all your other requests to stop/slow? If so I might look at your underlying architecture first. But if, in the end, this is an issue I don't think setting a hard limit on page size is bad.

Question: When I user GETs the URI http://xxx/user?page=1 does the response have a link in it to the next page? previous page? If not then it's not really RESTful.