Best way for designing a pagination endpoint in a RESTful Web Service

Question

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.

1. Send the pagination information via query parameters on the /entities endpoint with a GET request. For example, /entities?page=1&size=10

2. 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.

Answer 1

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.