AIP-4233

Automatic pagination

Many API responses, particularly to list and search methods, are paginated (AIP-158). Users calling these methods are then required to implement their own pagination logic, which is common boilerplate.

Guidance

Client libraries may provide automatic resolution of pagination (meaning that it performs requests in the background on an as-needed basis).

Pagination can be inferred for an RPC when all of the following conditions are met:

• The request message contains an int32 page_size field.
• The request message contains a string page_token field.
• The response message contains a string next_page_token field.
• The response message contains one non-primitive repeated field.

Client library generators implementing this feature must ensure that it is a backwards-compatible change to add client-side pagination functionality where it was previously absent.

Implementing pagination

For the client library to implement pagination (as defined by AIP-158), it should use the next_page_token value from the response message to populate the page_token value of an otherwise-identical request message, continuing indefinitely until the next_page_token value is empty.

Important: Client libraries that are implementing automatic resolution of pagination should only perform requests for future pages on an as-needed basis, and avoid greedily resolving potentially long and unnecessary result sets.

Client libraries that are implementing automatic pagination must still provide access to the individual fields on the response message, in the usual fashion.

Note: If the response message has more than one non-primitive repeated field, the first one (in order of appearance in the file and field number) is used. If the first field by order of appearance in the message and the first field by field number do not match, code generators that implement automatic pagination should fail with an error.