Pagination support ?

[r-sreesaran]

Most of the Request contains the number of records that the server needs to send back in response.
Since this has been widely used already, it would be good to have it as part of the specification.

This was inspired by:
https://jsonapi.org/format/#fetching-pagination

1. To have a Reserved header or query parameter for pagination.
2. To have a option to specify the default value.
3. To have a reusable component.

Example:
https://jsonapi.org/examples/#pagination

[MikeRalphson]

I think the problem is the number of ways pagination support can be implemented. OpenAPI aims to support many (but not all) existing APIs rather than imposing one preferred method or best-practice.

Personally I feel OpenAPI should support all the mechanisms by which pagination (and sorting, and filtering etc) are implemented, such as headers, querystring parameters etc rather than specific guidelines. If we are missing anything in the specification to support jsonapi pagination etc, please let us know.

[r-sreesaran]

Open API should support all possible ways of pagination rather than just one approach.
But the template or the ways to represent them in Header or query parameter needs to be defined, as in a reserved word that would represent the pagination. As is the case for Response too. For example

In case of Request using query :
GET /articles?page[number]=3&page[size]=1

Response :
"self": "http://example.com/articles?page[number]=3&page[size]=1",
"first": "http://example.com/articles?page[number]=1&page[size]=1",
"prev": "http://example.com/articles?page[number]=2&page[size]=1",
"next": "http://example.com/articles?page[number]=4&page[size]=1",
"last": "http://example.com/articles?page[number]=13&page[size]=1"

Defining the Request and Response helps in client generation using OAI document.
As of now this is not possible.

[MikeRalphson]

Ok, I see you are (mainly) talking about a specific serialisation format for query parameters, not generic pagination support (I think 'hard-coding' pagination parameter names and defaults would be a mistake). Please take a look at existing issue #1706 and see if this is a duplicate. Thanks

[vibhus]

@MikeRalphson is there a document that I can refer on how various pagination types in request/response are supported.

As you pointed out earlier, the spec should support most of the pagination methodologies used across APIs. E.g. Pageable, HATEOAS, Header based pagination, etc.

I am trying to build a common algorithm that outputs (say) a list UI out of any given OpenAPI document which supports server side pagination. In order to hook the pagination UI controls with the AJAX request and response, I may need to know a few things in advance (like what is the pagenumber/size/sort param in request and what is the totalRecords field in the response body, etc).