Proper way to respond to a rest paged request

Question

I want to create a REST compliant endpoint in Spring. The endpoint is supposed to allow pagination.

The request is quite simple, GET to url/resource?page=1&pageSize=20. The problem is the request.

I have found 2 big ways of returning the data:

Return a custom object containing:

{
    "page": 1,
    "pageSize": 20,
    "content": [
         {...},
         {...}
         ...
    ]
}

The problem with this method is that it no longer returns a resource, it returns a wrapper to the resource.

Set X-Total-Count custom header when you give the response from backend:

[
   {...},
   {...}
   ...
]

This resolves the resource issue, but it makes the endpoint harder to use, which is counter-intuitive since it requires extra work to implement as well.

I wanted to know, what standards are more widely used and why? What is the "new" approach to this? What should I stay away from? Is there a way to satisfy both needs?

Thanks in advance!

Possible duplicate of [Pagination response payload from a RESTful API](https://stackoverflow.com/questions/12168624/pagination-response-payload-from-a-restful-api) — Mike, Sep 30 '19 at 13:40

score 0 · Accepted Answer · answered Sep 30 '19 at 15:51

The most common practice I see in API's I use is your first example with an object wrapper:

{
    "page": 1,
    "pageSize": 20,
    "content": [
         {...},
         {...}
         ...
    ]
}

Usually, this object wrapper is implemented with any call to a GET /resources endpoint. When users call a GET resource/{resourceId} endpoint on the other hand, there is no object wrapper.

This is just my opinion relating to what I see other API's use, but I have written close to 100 different API integrations so I have seen a fair amount.

Proper way to respond to a rest paged request

1 Answers1