[ADP-312] Pagination
reviewing phase 1
Correct OpenAPI examples
Overview
Pagination in RESTful APIs is a technique for dividing large datasets into smaller, more manageable chunks or "pages." This helps improve performance, reduce server load, and provide a better user experience.
There are mainly two methods of pagination: offset-based pagination and cursor-based pagination.
Offset-based Pagination
Offset-based pagination uses an offset value to specify the starting point of the dataset and a limit to specify the number of items to retrieve.
Example
GET /resources?offset=20&limit=10 HTTP/1.1{
"resources": [ /* Resources from offset 20 to 29 */ ],
"meta": {
"offset": 20,
"limit": 10,
"totalItems": 100
},
"links": {
"self": "/resources?offset=20&limit=10",
"next": "/resources?offset=30&limit=10",
"prev": "/resources?offset=10&limit=10",
"first": "/resources?offset=0&limit=10",
"last": "/resources?offset=90&limit=10"
}
}WARNING
HATEOAS is used here to provide next and previous links, but HATEOAS is not recommended in this guideline.
Cursor-based Pagination
Cursor-based pagination uses a cursor (usually a unique identifier) to fetch the next set of results.
Example
GET /resources?cursor=abc123&limit=10 HTTP/1.1{
"data": [ /* Resources starting after cursor abc123 */ ],
"meta": {
"next_cursor": "def456",
"limit": 10
},
"links": {
"self": "/resources?cursor=abc123&limit=10",
"next": "/resources?cursor=def456&limit=10"
}
}WARNING
HATEOAS is used here to provide next and previous links, but HATEOAS is not recommended in this guideline.
Guidance
You SHOULD choose a pagination convention and use common query parameters for pagination. Currently, cursor-based pagination is more common.
You SHOULD use common query parameters for pagination, namely:
cursor,offset,limit.You SHOULD provide links to the next/previous pages in the response headers, see ADP-145: Link for details.
httpLink: <https://api.example.com/resources?cursor=test123>; rel="next", <https://api.example.com/resources?cursor=test123>; rel="prev",
Example
OpenAPI Example
openapi: 3.1.0
info:
title: Example API
version: 1.0.0
paths:
/resources:
get:
summary: Retrieve resource list
parameters:
- name: page
in: query
description: Page number for pagination
required: false
schema:
type: integer
- name: filter
in: query
description: Filtering criteria
required: false
schema:
type: string
- name: sort
in: query
description: Sorting order
required: false
schema:
type: string
responses:
'200':
description: Paginated resource list
headers:
Link:
description: Pagination links
schema:
type: string
content:
application/json:
schema:
type: object
properties:
resources:
type: array
items:
type: object
total:
type: integer
page:
type: integer
pageSize:
type: integer