Pagination divides a large collection—or a large single resource—into manageable chunks retrieved through multiple API requests. Each request returns results plus a cursor for continuing, avoiding oversized responses and excessive server transfers. section 21.0 section 21.2
Use pagination deliberately and follow these rules:
- Accept a maximum page size rather than promising an exact size; the service may return fewer results before the page is full. section 21.7
- Return a nextPageToken when more data exists, and treat its absence—not an empty results array—as the completion signal. section 21.7
- Use opaque page tokens instead of page numbers; consumers needing a particular position should combine filters with ordering. section 21.2 section 21.4.2
- Design the fields from the beginning, because changing an all-results response into paginated responses can break clients that expect one complete response. section 2.4.2
Listing messages with cursor pagination
A messages endpoint can accept parent, pageToken, and optional maxPageSize, then return results and nextPageToken. The client repeats the request with the returned token until no nextPageToken remains. The same design can page through large resource content by returning chunks, a field mask, and a continuation token. section 2.4.2 section 21.3.4
Listing 21.4 Final API definition
abstract class ChatRoomApi {
@get("/chatRooms")
ListChatRooms(req: ListChatRoomsRequest): ListChatRoomsResponse;
@get("/{id=chatRooms/*/messages/*/attachments/*}:read")
ReadAttachment(req: ReadAttachmentRequest): ReadAttachmentResponse;
}
interface ListChatRoomsRequest {
pageToken: string;
maxPageSize: number;
}
interface ListChatRoomsResponse {
results: ChatRoom[];
nextPageToken: string;
}
interface ReadAttachmentRequest {
id: string;
pageToken: string;
maxBytes: number;
}
interface ReadAttachmentResponse {
chunk: Attachment;
fieldMask: FieldMask;
nextPageToken: string;
}
Inspect the consolidated API definition covering collection pagination and paging inside a single large resource. section 21.3.5
