API Design Trends: AI, Security, and Automation
For developers building services in 2026, an API is the set of rules that lets one piece of software request data or…
When a client requests a large collection from an API, the server should return a manageable portion and tell the client how to get the next portion. That arrangement is pagination. Each portion is a page, and the page size is the maximum number of records the client asks the server to return.
API designers use several ways to divide a collection into pages. Page numbers and offsets tell the server where to start. A cursor marks a position so the client can continue from there, and a continuation token carries information the server needs to continue. A next-page link gives the client the next request to make. A timestamp or sequence checkpoint marks how far the client has retrieved changes. These methods can work together: a next-page link can contain a cursor, and an opaque token can carry other details the server needs to continue.
Choose a method based on the collection’s size, how often its records change, and whether clients need to jump to a particular page. Whichever method you use, define a stable order and set a maximum page size. Make it clear when the collection ends.
A client requests a numbered page and a page size:
GET /orders?page=3&page_size=25
This format suits interfaces that show page numbers or let users jump to a specific page. A common implementation uses the page number and page size to calculate how many records to skip. For example, page 3 with 25 records per page starts after 50 records. The parameter names do not require this approach; JSON:API supports page-number parameters without specifying how the server retrieves the records.
Page-number pagination suits collections that are modest in size and change relatively little. If the server uses a large offset to reach a deep page, the database still has to compute the skipped rows. Inserts or deletions before that page can also shift its contents. Set a predictable sort order, including a unique tie-breaker when sort values can repeat.
A client supplies the number of records to skip and the maximum number to return:
GET /orders?offset=50&limit=25
Offset-and-limit pagination lets a client set how many records the server skips and how many it returns. A database query can do this with OFFSET and LIMIT.
This approach fits smaller or relatively stable collections, especially when clients need arbitrary starting positions. For deep offsets, the database must still compute the skipped rows, and changes between requests can cause records to appear twice or be missed. PostgreSQL’s documentation warns that predictable ordering is necessary for consistent subsets and that skipped rows still have to be computed. For large or frequently changing collections, compare this approach with cursor pagination.
A cursor marks a position in an ordered collection. With keyset pagination, the server uses values from the last record the client received to find the next records, rather than counting and skipping rows. A request might look like this:
GET /orders?limit=25&after={cursor}
For example, the server might order records by creation time and then by a unique ID. The ID breaks ties when several records share a timestamp. Cursor pagination suits large collections, feeds, and collections that change while a client traverses them. It avoids deep offsets when the data store can efficiently seek from the cursor position.
Explain what happens to later pages when records change during traversal. A cursor can reduce shifts in page contents, but it does not freeze the collection at one point in time. Document how new, updated, or deleted records affect later pages. Cursor APIs also make it difficult to jump directly to an arbitrary numbered page. Microsoft’s Data API Builder guidance for $after describes a keyset approach, but other cursor APIs may behave differently.
The server returns an opaque continuation token for the client to send with its next request. “Opaque” means clients treat the token as an uninterpreted value: they pass it along rather than decode or construct it.
{
"items": [{"id": "o_123"}],
"next_page_token": "server-generated-token"
}
The server can encode a cursor in the token or use it to refer to stored state. The token can also carry other continuation details. This approach helps keep internal query details out of the public API and gives the server room to change how it retrieves records.
Document how clients should handle invalid or expired tokens and whether they must preserve filters and sort parameters. Also state whether clients can change page size while continuing. Google’s AIP-158 guidance recommends URL-safe, opaque tokens and says a token must not grant authorization; the server still checks authorization on every request.
A server can return the complete URL a client should request next. The URL may appear in the response body or an HTTP Link header. For example, GitHub’s REST API uses link relations such as next, prev, first, and last.
A next-page link is a continuation interface, not a separate retrieval algorithm. It can point to an offset-based page, a cursor, or a request that includes a token. Clients should follow the provided URL rather than rebuild it, because the URL can preserve filters, sorting, and continuation state. JSON:API’s pagination links likewise do not prescribe one underlying pagination strategy. For more on this interface, see implementing link headers.
A client can request records after a timestamp or sequence checkpoint:
GET /events?since=2026-11-01T00:00:00Z
This method fits incremental synchronization, where a client checks for changes since its last successful request. It does not necessarily let the client retrieve every record in a collection. GitHub’s commits endpoint documentation describes a since timestamp filter.
A timestamp alone does not guarantee that a client captures every change exactly once. Define how precise timestamps are and explain how the API handles records with equal timestamps, updates that arrive late, and changes to records the client has already seen. A sequence that only increases, or a timestamp combined with a unique tie-breaker, can mark a precise checkpoint. Some clients request an overlapping time range and remove duplicate results. The API must document enough about its behavior for clients to do this reliably.
Use page numbers or offsets when collections are small enough that simple navigation and arbitrary page access matter more than deep traversal. Use cursors for large or frequently changing collections when the server can provide a stable order and efficiently seek from a position. Use opaque tokens when the server needs to hide continuation details, and provide next-page links when clients should follow a ready-made request. Use time or sequence checkpoints when clients need changes since a prior poll.
A next-page link can carry an opaque token, and a cursor can use a timestamp plus an ID, so you can combine these choices. When designing for high-volume collections, consider how the data store will seek to each page; this high-volume pagination discussion explores that concern.
Every paginated endpoint needs a deterministic order: the same request conditions must produce a defined sequence. If the primary sort value can repeat, add a unique tie-breaker. Without predictable ordering, records can move between pages even when the collection does not change. PostgreSQL also cautions that LIMIT and OFFSET can return inconsistent subsets without a specified order.
Set a default page size and a maximum, then validate or cap client requests consistently. Treat the page size as a limit rather than a promise that every response contains exactly that many records. Google’s AIP-158, for example, permits a service to return fewer records than requested, including zero, before the collection ends. Slack also tells clients to check the cursor rather than infer completion from a short page in its pagination documentation.
Specify the end condition: a client might stop when the response has no next link or when the API omits the continuation token. Do not require clients to guess that the collection has ended because a page contains fewer records than the requested size.
Have the data store filter, sort, and paginate records instead of retrieving the entire collection and trimming it in memory. The Azure Architecture Center’s API guidance recommends doing this in the data store and using a defined, repeatable order.
When the API requires it, keep the client’s filters and sort parameters the same across requests. Have the client follow a continuation URL exactly as the server supplied it, or send a returned token back unchanged. Explain token errors and expiration so clients know whether to start over or report a failure. AWS describes how its SDK paginators handle tokens and continue until the service returns no token.
Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.
Take a look at vroni.com