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.

Answer 2

I believe there is no official "standard" for RESTful web services. But there are many recommendations/implementations by different vendors.

Your first way, using query parameters would be the correct one. The different HTTP methods (GET, PUT, DELETE, POST) are used for different kinds of operations. I've never heard of them being used for modifying existing operations.

Please see Wikipedia - REST

Answer 3

Based on the HATEOAS (Hypermedia as the Engine of Application State) standard, the response is supposed to be linked with previous and next page.

/entities?page=1&size=10 is preferred over /entities/1/10 as (strictly speaking) 1/10 isn't a resource to be located via URI.