What is the correct way to pass the pagination data in Sponse REST?

Asked

Viewed 2,718 times

4

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 pagination information (page number, page size, ordering, etc)

In the body of the answer

  • Pagination information stays in the body, such as totalPages, totalElements, size, number, etc.;
  • The list of elements is packaged in an array content, being part of the returned page object;

In the answer header

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

Taking into account the design of a REST API, what is the correct way to pass pagination data in Sponse?

java rest spring-mvc restful

  • This is a delusion of complex design, I do not believe that there is a "correct" answer... That being said, there is a tendency to frame pagination in the HATEOAS standard with information about pagination in the body, as well as links to other pages (first, next, previous, last). This pattern is very practical, especially when the client has the respective methods next, Previous, etc implemented for you

3 answers

5


I believe that the correct thing to do would be to pass this information in the Header of the Answer, as it constitutes meta data of the request (additional information) and therefore should be in the Header of the reply. With this payload would store information that actually has value for an application, which would even make it easier to understand the client that will consume your API.

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

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

Content-Range to indicate the range of the returned resource list and the total resources of the full query and status '206 Partial Content' to indicate that this is only a part of the listing (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Range)

Additionally, you may be using the head link to provide navigation information for your response (https://www.w3.org/wiki/LinkHeader):

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"

  • I also discovered that there is a standardization for this, called Web Linking RFC 5988 (http://tools.ietf.org/html/rfc5988).

1

I believe that the most interesting thing is to pass in the body of the answer the information of the page.

Viewing the standard JSON API you can check that they also do this.

http://jsonapi.org/examples/#pagination

1

Good afternoon Murillo, From what I have studied and implemented in some projects of REST Apis, I get the 1st option, this because the information totalPages, totalElements, size, number, are data that make up the information, so I believe that it makes more sense to be present in the body.

Here where I work, we have a large flow of traffic data, and we use the 1st option, the header we use to handle working data from Apis such as tokens and other types of configuration and management data.

Browser other questions tagged java rest spring-mvc restful

You are not signed in. Login or sign up in order to post.