Basic pattern
EveryList, Entitlements, and Grants method returns one page of results and a token for the next page. The SDK passes the token you returned back to your next call in opts.PageToken.Token:
Page size
The SDK passes the page size it wants inopts.PageToken.Size, which is 0 when the SDK doesn’t specify one. The SDK asks for at most 250 items per page. Use it when your API takes a page size, and fall back to a default:
Pagination strategies
APIs paginate results differently. Your connector converts the token to whatever the API expects:Cursor-based
When the API returns an opaque cursor, pass it straight through as the next page token:Offset-based
Store the next offset as the token:len(resp.Users) == limit) is a fallback signal. That fallback costs one extra request when the last page is exactly full.
Link header
For APIs that return the next page in an RFC 5988Link header, the uhttp package parses the header for you. uhttp.WithNextLinkPagination pushes the rel="next" URL onto the bag you pass it, so give it a new bag and return that bag as the next token:
bag.PageToken() after you unmarshal the token. See Nested pagination with Bag.
For APIs that can silently drop their cursor, uhttp.WithPaginationData makes the request fail when a successful response has no pagination data. Without it, the sync ends after one page and looks complete.
LDAP paging
LDAP servers return a paging cookie. Encode it as the token:Nested pagination with Bag
When a single call needs to page through more than one thing, one string isn’t enough state. For example, “page through the admins of a group, then page through its members” needs to remember which list you’re in and where you are in it. The SDK’spagination.Bag holds that state as a stack and serializes it into the page token.
How Bag works
ABag is a stack of PageState values. The top of the stack is the current state:
Prefer
NextToken. It does the advance and the serialization in one call, and its return value is the page token you hand back to the SDK.
Page through one list
The pattern for a single list is: unmarshal, push an initial state if the bag is empty, fetch with the current token, and advance withNextToken.
Page through several lists
To page through two lists in one method, push one state per list. The state you push last is current, so it’s processed first. When a list runs out,NextToken("") pops its state, and the next call continues with the list below it:
pagination.GenBag[T] holds a stack of your own struct type. Create one with pagination.GenBagFromToken[T](&opts.PageToken).
Expired page tokens
Some APIs reject a cursor after a period of time. When the API rejects the token the SDK gave you, return a restart error fromList, Entitlements, or Grants instead of failing the sync:
restartToken. An empty restartToken restarts from the first page. The restart only works when the error comes straight from one of those list calls, and any other source fails the sync.
Modeling hierarchies
Real systems often have deep hierarchies. Declare the parent-child relationships, and the SDK walks the tree for you.Two mechanisms connect parent and child
1. The parent declares its child types with theChildResourceType annotation:
WithParentResourceID:
List for a child type, it passes the parent’s ResourceId, so you can scope your API call to that parent.
Example: GitHub hierarchy
Organization builder:List:
When to use hierarchies and when to use flat models
Common hierarchy mistakes
Pagination invariants
The SDK checks for common pagination bugs:- The token must change. If a page returns the same non-empty token it received, the sync fails with a “next page token unchanged” error. The SDK doesn’t detect longer loops, such as a token that alternates between two values.
- An empty token means done. Return
""when there are no more pages. - Respect the requested page size. Use
opts.PageToken.Sizewhen your API takes a page size.