Open markcowl opened 2 years ago
@johanste will discuss this with the API Review Board and report back.
Hello 👋🏻 - I found this issue via the TypeSpec docs. Are there any updates in the pagination space?
For context, I plan to build paginated APIs in the coming week(s), so I’m asking in advance. TypeSpec may already fully support what I need though.
@bterlson please use this as the imp issue for generic paging support
est: 21 pri: 1
We need to support pagination in TypeSpec. There are a few goals with this proposal:
It is important to note that while there are some general high-level patterns in play, this list is not exhaustive (people do all kinds of things!) and that for some patterns there are variants in terms of the names of the fields, the location of the fields (header, query string, request/response body), and additional metadata that is present.
Pagination Decorators
The following decorators are proposed for the core compiler.
In order for an operation to be paginated, the following requirements must be met:
@list
decorator applied.@offset
or@pageIndex
@nextLink
Link
type with a relation type of "next"The requirements for 2 are not exclusive - an operation might have any or all of these items, in which case it is up to clients to decide which method to use for pagination.
General pagination parameter decorators
@pageSize
: the parameter that controls the maximum number of items to include in the page.Client-driven pagination
Client-driven pagination is achieved by annotating the parameters of the endpoint with the following decorators:
@offset
: the number of items to skip. Clients are expected to track how many items have already been seen in order to set this properly.@pageIndex
: the page of tiems to return. Clients are expected to track the current page in order to set this properly.Either
offset
orpageIndex
is required in order for clients to generate a client-driven paginated interface.Server-driven pagination
Server-driven pagination is achieved by annotating a paginated response with the following decorators:
@continuationToken
: the token to get the next page, specified on both an operation parameter and in the response.@nextLink
: the link to the next page.@prevLink
: the link to the previous page.@firstLink
: the link to the first page.@lastLink
: the link to the last page.Either
continuationToken
ornextLink
must be defined in a paged response, and everything else is optional. The type of the Link fields must beurl
orrelativeUrl
. WhencontinuationToken
is provided, clients are expected to assemble the nextLink by passing the response's continuation token to the corresponding parameter of the paginated operation, and copy all other parameters as-is.RFC 5988 Link type
RFC 5988 defines a Link which is comprised of:
title="next page"
).This RFC defines link relation types useful for pagination, and is commonly used for this purpose (e.g. GitHub and DigitalOcean APIs). In order to support pagination using this RFC without creating new must-understand decorators or special serialization logic, we need the following types defined:
Examples
Client-driven pagination
Offset and limit:
Pages:
Next and prev links in response envelope
Or, nested in the envelope somewhere:
Next and prev links in header (RFC 5988)
Or, using link headers with custom attributes: