Best way for designing a pagination endpoint in a RESTful Web Service
api-design, pagination, rest, web-services
Solution
As aljo f mentioned, there is no official standard. But looking for best practices I came across this site:
http://www.restapitutorial.com
In the resources page there is a link to download a .pdf that contains the complete REST best practices suggested by the author. In which among other things there is a section about pagination.
The author suggest to add support to both using a Range header and using query-string parameters.
Request
HTTP header example:
Range: items=0-24
Query-string parameters example:
GET http://api.example.com/resources?offset=0&limit=25
Where offset is the beginning item number and limit is the maximum number of items to return.
Response
The response should include a Content-Range header indicating how many items are being returned and how many total items exist yet to be retrieved
HTTP header examples:
Content-Range: items 0-24/66
Content-Range: items 40-65/*
In the .pdf there are some other suggestions for more specific cases.
Problem
I have my `/entities` endpoint on my RESTful Web Service, which returns all the stored entities on the database, if called with a `GET` request. What I would like to create now, is a pagination functionality. The ability to retrieve only a page of those results, and not all the entities, just for the matter of minimizing the response's size. I am thinking of two ways of doing this. Send the pagination information via query parameters on the `/entities` endpoint with a `GET` request. For example, `/entities?page=1&size=10` Use another `HTTP Method`, like `OPTIONS` (I know it's not designed to be used for this kind of thing). I don't handle `OPTIONS` requests on my Web Service, and I may take advantage of that, while keeping the essence of a RESTful web service, that is, using different `HTTP Methods` for different actions. In that case, the endpoint could be something like this: `/entities/1/10`, which (I think) is more user-friendly. Both alternatives can be implemented, and I wanted to know beforehand which one would be more compliant with the REST design standard.