Skip to content
Merged
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 19 additions & 3 deletions aip/general/0158.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,9 +110,10 @@ For example:
first 50 results were returned on the first page) and a `skip` value of `30`
returns a single page of results starting with the 81st result.

If a `skip` value is provided that causes the cursor to move past the end of
the collection of results, the response **must** be `200 OK` with an empty
result set, and not provide a `next_page_token`.
If a `skip` value is provided that cannot be fulfilled e.g. due to latency of
querying a massive data set, the response **must** be `200 OK` with an empty
result set. If it is _known_ to put the cursor beyond the total size of the
collection, the response **must not** include a `next_page_token`.

### Opacity

Expand Down Expand Up @@ -176,8 +177,23 @@ paginate) is reasonable for initially-small collections.

[list]: ./0132.md

## Rationale

### Degraded `skip` response

Large collections, complex queries, and globally distributed data can all
contribute to a paginated method being unable to quickly or confidently fulfill
a given `skip` request. Backend queries can timeout, data collation can take
time, and the end user experience need not suffer as a result. In such cases,
the pagination interface can be leveraged to keep the client engaged by
providing a `next_page_token`, while the service collects an appropriate result.
When the service is definitively determine that the requested `skip` exceeds
Comment thread
noahdietz marked this conversation as resolved.
Outdated
available results, the pagination interface is again applied and
`next_page_token` is omitted to signal the end of results.

## Changelog

- **2025-05-12**: Clarify degraded skip response guidance
- **2020-05-24**: Clarified that adding pagination breaks client
libraries.
- **2020-05-13**: Added guidance for skipping results.
Expand Down