What is the correct way to pass the paging data in the REST response?

3

In more robust applications where a table can have millions of records, it is important to implement paging in a REST API. I have seen in some projects two ways to return paging information (page number, page size, sort order, etc.)

In the body of the answer

  • The pagination information stays in the body, such as totalPages, totalElements, size, number , etc.
  • The element list is wrapped in a content array, part of the returned page object;

In the response header

  • The paging information is header, such as totalPages, totalElements, size, number, etc.
  • The list of elements is the returned array;

Given the design of a REST API, what is the correct way to pass the paging data in the response?

    
asked by anonymous 12.04.2017 / 19:31

3 answers

4

I believe the correct thing would be to pass this information to the Header of the response, since they are meta data of the request (additional information) and therefore should be in the Header of the response. With this payload would store information that in fact has application value, which would even facilitate the understanding of the client that will consume its API.

For example, the request GET /recursos?intervalo=0-25 could receive the header as a response:

HTTP/1.1 206 Partial Content
Content-Range: 0-25/100 
...

Content-Range to indicate the resource list range returned and the full query resource full and status '206 Partial Content' to indicate that this is only a part of the listing ( link )

In addition, you can use the head link to provide navigation information for your answer ( link ):

p>
Link : <https://api/recursos?intervalo=0-25>; rel="primeiro", 
<https://api/recursos?intervalo=0-25>; rel="anterior", 
<https://api/recursos?intervalo=51-76>; rel="proximo", 
<https://api/recursos?intervalo=51-76>; rel="ultimo"
    
18.04.2017 / 20:54
1

Good afternoon Murillo, From what I have studied and implemented in some REST API projects, I get the 1st option, because the information totalPages, totalElements, size, number, is data that compose the information, so I believe it makes more sense to be present in the body. / p>

Here, where we work, we have a large flow of traffic data, and we use the first option, the header we use to handle the functioning data of the APIs as tokens and other types of configuration and management data.

    
12.04.2017 / 20:27
1

I think the most interesting thing is to pass the information on the page in the body of the answer.

Viewing the JSON API pattern you can verify that they also do this.

link

    
19.04.2017 / 05:25