Pagination in OpenAPI

Describing a collection of resources in an API may be simple at first, but certain features like pagination can make it more complex. Pagination is a common requirement for APIs that return large sets of data, which allows for a subsection of a collection to be returned (maybe only 20-100 resources) to avoid overwhelming the server, the client, and all the network components in between.

This is usually implemented as a query parameter, such as ?page=1 or ?cursor=abc123, so that a client can request a specific page of results. The API can then return a subset of the data, and depending on the specific pagination strategy used there could also be metadata about the total number of items and the total number of pages. That metadata allows a client to display pagination controls in the interface such as “Page 1”, “Page 2”, or simply “Next” and “Previous” buttons.

You can learn more about various approaches to pagination in the API design guide here.

This guide will show you how to implement pagination in OpenAPI, regardless of which strategy the API has chosen.

Pagination with query parameters

Query parameters are a common way to implement pagination in APIs. The most common query parameters for pagination are page and limit, which specify the page number and the number of items per page, respectively. This is a common approach for paginating through large sets of data, and is often used in REST APIs.

Adding the page and limit query parameters advertises to the API consumers that the API supports pagination. Pagination is mentioned in the description too, increasing the chance of it being noticed by any API client developers.

The page parameter specifies the page number the API should return, and the optional limit parameter specifies the number of items to return for that page. This is helpful for mobile apps that want to return a grid of data to the user. For example a 3x3 grid of items, which would require 9 items to be returned, instead of the default 10 giving the user a blank space in the grid.

Describing pagination metadata

When implementing pagination, a common practice is to include metadata in the response to provide information about the total number of items, the current page, and the total number of pages. This metadata can be included in the response body, or sometimes is done with custom HTTP headers (which is frowned upon but done anyway).

Using a meta object in an array would not work, so APIs often wrap the collection with an “envelope” which might be something like data.

If the API is doing this, the response can be described with the following OpenAPI:

This meta object can be defined in components and referenced to avoid repeating it in every endpoint.

Learn more about components here.

Describing pagination with response links

Adding a query parameter to the API is a good start, but asking API clients to construct URLs from little bits of data is always confusing and a recipe for disaster. REST APIs offer the ability to send links which can be used to crawl the API following links like a browser would.

If the API supports pagination links they need to be described so clients can use them. The most common way to do this is to include a links object in the response.

That links object can be described in OpenAPI like using the following approach:

In this example, the links object contains three links: self, next, and prev. The self link points to the current page of results, while the next and prev links point to the next and previous pages of results, respectively. The links object is described in the OpenAPI specification using the links object, which is a common way to describe hypermedia links in OpenAPI.

Describing pagination with HTTP headers

Some APIs use custom HTTP headers to provide pagination information instead of trying to wedge the information into the response body and using data and meta. This has the benefit of keeping the JSON clean and tidy, but can be confusing as there is no standard for pagination headers. The Link header is a standard HTTP header that can be used to provide links for general HATEOAS purposes but also for pagination specifically, but it does not have anywhere to pass pagination metadata about numbers of pages.

For example, an API might use something like X-Total-Count header to indicate the total number of items in the collection, and the X-Page and X-Per-Page headers to indicate the current page and the number of items per page, then next and previous links in the Link header.

However the API is doing pagination, OpenAPI can describe it. The most important thing is to be consistent and clear about how pagination works in the API reference documentation, and if possible write a custom guide for explaining pagination in an API more specifically so that API consumers can get it right.

Speakeasy SDK pagination

Speakeasy SDKs support pagination out of the box, and can be configured to automatically handle pagination for any API, allowing clients to focus on working with data instead of learning about specific pagination strategies.

To configure pagination, add the x-speakeasy-pagination extension to the OpenAPI description:

The x-speakeasy-pagination configuration supports offsetLimit, cursor, and url implementations of pagination, and allows the generated SDKs to extract the proper response data from the API instead of having to split up data and metadata manually.

Learn more about pagination with Speakeasy SDKs here.