public-api-docs

📖 Pagination

When accessing APIs of the Wunder Platform most list endpoints are paginated.

Why Pagination

Performance Optimization: Fetching, transferring, and rendering large amounts of data at once can consume significant computational resources and bandwidth. Pagination allows for fetching data in chunks, reducing the load on both server and client systems.
User-Friendliness: Displaying data in smaller, comprehensible chunks helps users navigate the information more effectively. Endless scrolling or massive tables are hard to comprehend and use.
Scalability: As datasets grow, a paginated approach scales better, ensuring that APIs, databases, and frontends are not overwhelmed.

Pagination in Wunder Platform APIs

Request

Paginated list endpoints support the following query parameters to paginate through results. Paginated endpoints usually come with a default configuration that is used if none is provided in the request.

Request Parameter	Default	Purpose
`page`	0	Define which page should be returned (so depending on the defined size, skip the first X results). Zero-based.
`size`	50 unless overwritten by an endpoint (some return 500 or up to 1000 results)	Define how many results should be in the returned page. At maximum we allow a size of 5000, and some endpoints might specify a lower maximum.
`sort`	usually by ID DESC	Define the sorting order of the results. See the section below for more details.

Response

The API will contain the following HTTP headers to give the consumer of the API information about the paginated result.

Header	Purpose
`X-Pagination-TotalPages`	Total number of available pages. Calculation: `ceil(totalElements / size)`
`X-Pagination-TotalElements`	Total number of results across all pages
`X-Pagination-Number`	Current page number
`X-Pagination-NumberOfElements`	Number of elements of the currently returned page (can be less than size on the last page)
`X-Pagination-Size`	Number of elements per page (should be the same as above except on the last page)
`X-Pagination-First`	Boolean value indicating if it’s the first page
`X-Pagination-Last`	Boolean value indicating if it’s the last page

Filtering and Sorting paginated endpoints in Wunder Platform APIs

Sorting

Paginated list endpoints generally also allow to sort the results for specific properties. Supported properties depend on the specific endpoint.

By adding a sort query parameter, the client can specify:

The field to sort by (e.g., id, createdAt, or updatedAt).
The direction of sorting: ascending asc (default) or descending desc.

Examples:

sort=id,asc sorts by id in ascending order. Can be shortened to sort=id
sort=updateAt,desc sorts by updatedAt in descending order

Filtering

Paginated list endpoints generally also allow to the results for specific properties. Similar to sorting the supported properties also depend on the specific endpoint.

Filtering works by specifying the property to filter for as a query parameter, followed by the value. For example id=10 will find elements that have 10 as id (should only be one).

The concrete logic of how filtering is applied depends on the datatype of the property:

String: field contains the value ignoring any casing. Only providing one value is supported.
Identifier (Number): will only return results where the identifier matches, can be passed multiple times to return results that match any of the passed parameter
Numbers: if a single value is provided then it filters for values equaling the value. If the parameter is provided twice it filters for values between both.
DateTime: if a single value is provided then it filters for values between the specified and the value plus 1 day. If the parameter is provided twice it filters for values between both.
DateTime for updatedAt: if a single value is provided then it filters for values between the specified date time and now. If the parameter is provided twice it filters for values between both.

Examples:

updatedAt=2025-02-08T00:02:00.000Z returns all entries that have been updated between 2025-02-08T00:02:00.000Z and now
updatedAt=2025-02-08T00:02:00.000Z&updatedAt=2025-02-21T00:02:00 returns all entries that have been updated between 2025-02-08T00:02:00.000Z and 2025-02-21T00:02:00
createdAt=2025-02-08T00:02:00.000Z returns all entries that have been created between 2025-02-08T00:02:00.000Z and 2025-02-09T00:02:00.000Z (one whole day)
createdAt=2025-02-08T00:02:00.000Z&createdAt=2025-02-21T00:02:00 returns all entries that have been created between 2025-02-08T00:02:00.000Z and 2025-02-21T00:02:00
id=10 returns all entries that have 10 as id (should only be one)
id=10&id=20 returns all entries that have 10 or 20 as id
user.id=10&user.id=20 returns all entries that match a user with id 10 or 20
name=Martin returns all entries where the name matches martin, ignoring any casing