Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Pagination response payload from a RESTful API

I want to support pagination in my RESTful API.

My API method should return a JSON list of product via /products/index. However, there are potentially thousands of products, and I want to page through them, so my request should look something like this:

/products/index?page_number=5&page_size=20 

But what does my JSON response need to look like? Would API consumers typically expect pagination meta data in the response? Or is only an array of products necessary? Why?

It looks like Twitter's API includes meta data: https://dev.twitter.com/docs/api/1/get/lists/members (see Example Request).

With meta data:

{   "page_number": 5,   "page_size": 20,   "total_record_count": 521,   "records": [     {       "id": 1,       "name": "Widget #1"     },     {       "id": 2,       "name": "Widget #2"     },     {       "id": 3,       "name": "Widget #3"     }   ] } 

Just an array of products (no meta data):

[   {     "id": 1,     "name": "Widget #1"   },   {     "id": 2,     "name": "Widget #2"   },   {     "id": 3,     "name": "Widget #3"   } ] 
like image 417
Chad Johnson Avatar asked Aug 28 '12 22:08

Chad Johnson


People also ask

How does pagination work on a REST API?

You can paginate the JSON response that is called from the REST API. The order of the data is retained from page to page. Given the ability to paginate, you can quickly populate tables and make new REST calls every time you go to the next page of the data on the table.

How does REST API implement pagination in Java?

3.In your service or in controller directly create a Pageable object and pass it as ContactRepository#fingAll() argument: final Pageable contactsPageable = PageRequest. of(pageNumber, pageSize);

What is pagination in JSON?

What is JSON Pagination? Pagination is the process of dividing a document into separate sequential pages that are related and have similar content. For JSON, pagination refers to displaying a little chunk of data for a large dataset (for example, the first 100 results from an API response containing 1000 items).


1 Answers

ReSTful APIs are consumed primarily by other systems, which is why I put paging data in the response headers. However, some API consumers may not have direct access to the response headers, or may be building a UX over your API, so providing a way to retrieve (on demand) the metadata in the JSON response is a plus.

I believe your implementation should include machine-readable metadata as a default, and human-readable metadata when requested. The human-readable metadata could be returned with every request if you like or, preferably, on-demand via a query parameter, such as include=metadata or include_metadata=true.

In your particular scenario, I would include the URI for each product with the record. This makes it easy for the API consumer to create links to the individual products. I would also set some reasonable expectations as per the limits of my paging requests. Implementing and documenting default settings for page size is an acceptable practice. For example, GitHub's API sets the default page size to 30 records with a maximum of 100, plus sets a rate limit on the number of times you can query the API. If your API has a default page size, then the query string can just specify the page index.

In the human-readable scenario, when navigating to /products?page=5&per_page=20&include=metadata, the response could be:

{   "_metadata":    {       "page": 5,       "per_page": 20,       "page_count": 20,       "total_count": 521,       "Links": [         {"self": "/products?page=5&per_page=20"},         {"first": "/products?page=0&per_page=20"},         {"previous": "/products?page=4&per_page=20"},         {"next": "/products?page=6&per_page=20"},         {"last": "/products?page=26&per_page=20"},       ]   },   "records": [     {       "id": 1,       "name": "Widget #1",       "uri": "/products/1"     },     {       "id": 2,       "name": "Widget #2",       "uri": "/products/2"     },     {       "id": 3,       "name": "Widget #3",       "uri": "/products/3"     }   ] } 

For machine-readable metadata, I would add Link headers to the response:

Link: </products?page=5&perPage=20>;rel=self,</products?page=0&perPage=20>;rel=first,</products?page=4&perPage=20>;rel=previous,</products?page=6&perPage=20>;rel=next,</products?page=26&perPage=20>;rel=last 

(the Link header value should be urlencoded)

...and possibly a custom total-count response header, if you so choose:

total-count: 521 

The other paging data revealed in the human-centric metadata might be superfluous for machine-centric metadata, as the link headers let me know which page I am on and the number per page, and I can quickly retrieve the number of records in the array. Therefore, I would probably only create a header for the total count. You can always change your mind later and add more metadata.

As an aside, you may notice I removed /index from your URI. A generally accepted convention is to have your ReST endpoint expose collections. Having /index at the end muddies that up slightly.

These are just a few things I like to have when consuming/creating an API. Hope that helps!

like image 166
codeprogression Avatar answered Oct 15 '22 15:10

codeprogression