Skip to content

Paging Operations

This doc details what emitters will generate for paging operations.

Using next link to indicate how to get the next page

Next link is an absolute url returned by the paging operation, which indicates how to get the next page. If the response does not return a next link, it indicates the last page of results. Next link should be annotated in the response model with @nextLink.

There are two ways to indicate a paging operation with @nextLink:

  1. Use @pagedResult and @items in Azure.Core lib.
op listWithPage(): UserList;


model User {
  id: string;
  name: string;
}


@pagedResult
model UserList {
  @items
  value: User[];


  @nextLink
  nextLink?: url;
}
class User(_model_base.Model):
    id: str = rest_field()
    name: str = rest_field()


def list_with_page(self, **kwargs: Any) -> Iterable["_models.User"]:
    ...
  1. Use the @list and @pageItems decorators from TypeSpec core.
@list
op listWithPage(): UserList;


model User {
  id: string;
  name: string;
}


model UserList {
  @pageItems
  value: User[];


  @nextLink
  nextLink?: url;
}
class User(_model_base.Model):
    id: str = rest_field()
    name: str = rest_field()


def list_with_page(self, **kwargs: Any) -> Iterable["_models.User"]:
    ...

Using continuation token to indicate how to get the next page

A continuation token is a string returned by a paging operation, which is used as a parameter value for the paging operation to get the next page. If the response does not return a continuation token, it indicates the last page of results. The request parameter that corresponds to the continuation token value in the paging operation should be decorated with @continuationToken. Similarly, the response property that contains the continuation token value should also be decorated with @continuationToken.

  1. Continuation token in query parameter and response body.
@list
op listWithPage(@query @continuationToken continuationToken?: string): UserList;


model User {
  id: string;
  name: string;
}


model UserList {
  @pageItems
  value: User[];


  @continuationToken
  continuationToken?: string;
}
class User(_model_base.Model):
    id: str = rest_field()
    name: str = rest_field()


def list_with_page(self, **kwargs: Any) -> Iterable["_models.User"]:
    ...
  1. Continuation token in header parameter and response body.
@list
op listWithPage(@header @continuationToken continuationToken?: string): UserList;


model User {
  id: string;
  name: string;
}


model UserList {
  @pageItems
  value: User[];


  @continuationToken
  continuationToken?: string;
}
class User(_model_base.Model):
    id: str = rest_field()
    name: str = rest_field()


def list_with_page(self, **kwargs: Any) -> Iterable["_models.User"]:
    ...
  1. Continuation token in query parameter and response header.
@list
op listWithPage(@query @continuationToken continuationToken?: string): {
  @header
  @continuationToken
  continuationToken?: string;


  @pageItems
  value: User[];
};


model User {
  id: string;
  name: string;
}
class User(_model_base.Model):
    id: str = rest_field()
    name: str = rest_field()


def list_with_page(self, **kwargs: Any) -> Iterable["_models.User"]:
    ...
  1. Continuation token in header parameter and response header.
@list
op listWithPage(@query @continuationToken continuationToken?: string): {
  @header
  @continuationToken
  continuationToken?: string;


  @pageItems
  value: User[];
};


model User {
  id: string;
  name: string;
}
class User(_model_base.Model):
    id: str = rest_field()
    name: str = rest_field()


def list_with_page(self, **kwargs: Any) -> Iterable["_models.User"]:
    ...