Pagination divides a large collection of API results into smaller pages that users retrieve separately. Collection endpoints such as GET /products use it to avoid sending millions of records in one response and overwhelming servers or databases. section 1.4 section 6.1
A pagination design commonly lets a client control:
- The page to retrieve, such as page=2. section 6.1
- The number of results per page, such as perPage=50. section 6.1
- Sorting and filtering options, which must also be treated as untrusted input. section 1.4
- An implementation pattern, including page-based, offset-based, or cursor-based pagination. section 6.1
Constraining a product listing
An unconstrained endpoint may accept GET /products?page=1&perPage=100000000. The request can put enormous pressure on the database and servers. A safer contract constrains page to a minimum of 1 and maximum of 100, and perPage to a minimum of 10 and maximum of 100. Filtering also requires care: a value such as ' OR 1=1;-- can cause SQL injection if it is inserted directly into a database query. section 1.4 section 6.1
Listing 6.2 Secure pagination
# file: ch06/6_1_safe_pagination.yaml
paths:
/products:
get:
parameters:
- name: page
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
- name: perPage
in: query
required: false
schema:
type: integer
minimum: 10
maximum: 100
Inspect the secure OpenAPI pagination listing and compare its minimum and maximum values with the vulnerable unconstrained version. section 6.1
