Pagination

PaginatedQueryParams

Query parameters for paginated routes. These parameters should be used on GET routes that support pagination.

Table

Parameter	Type	Default	Description
page	integer	`1`	The page to return
pageSize	integer	`100`	The number of items to return per page

Formats

A JSON example of this model.

{
  "page": 1,
  "pageSize": 100
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: PaginatedQueryParams.yaml
type: object
properties:
  page:
    type: integer
    minimum: 1
    maximum: 2147483647
    default: 1
    description: The page to return
  pageSize:
    type: integer
    minimum: 1
    maximum: 2147483647
    default: 100
    description: The number of items to return per page
unevaluatedProperties:
  not: {}
description: Query parameters for paginated routes

The TypeSpec code for this model.

/** Query parameters for paginated routes */
@Versioning.added(CommonGrants.Versions.v0_1)
model PaginatedQueryParams {
  /** The page to return */
  @query
  @pageIndex
  @minValue(1)
  page?: int32 = 1;

  /** The number of items to return per page */
  @query
  @pageSize
  @minValue(1)
  pageSize?: int32 = 100;
}

The Python code for this model.

class PaginatedQueryParams(PaginatedBase):
    """Parameters for pagination in a request query."""

The TypeScript code for this model.

export const PaginatedQueryParamsSchema = z.object({
  /** The page to return */
  page: z.number().int().min(1).nullish().default(1),

  /** The number of items to return per page */
  pageSize: z.number().int().min(1).nullish().default(100),
});

Changelog

Version	Changes	Schema
0.1.0	Added `PaginatedQueryParams` model	PaginatedQueryParams.yaml

PaginatedBodyParams

Body parameters for paginated routes. These parameters should be used on POST and PUT routes that support pagination.

Table

Parameter	Type	Default	Description
page	integer	`1`	The page to return
pageSize	integer	`100`	The number of items to return per page

Formats

A JSON example of this model.

{
  "page": 1,
  "pageSize": 100
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: PaginatedBodyParams.yaml
type: object
properties:
  page:
    type: integer
    minimum: 1
    maximum: 2147483647
    default: 1
    description: The page to return
  pageSize:
    type: integer
    minimum: 1
    maximum: 2147483647
    default: 100
    description: The number of items to return per page
unevaluatedProperties:
  not: {}
description: Body parameters for paginated routes

The TypeSpec code for this model.

/** Body parameters for paginated routes */
@Versioning.added(CommonGrants.Versions.v0_1)
model PaginatedBodyParams {
  /** The page to return */
  @pageIndex
  @minValue(1)
  page?: int32 = 1;

  /** The number of items to return per page */
  @pageSize
  @minValue(1)
  pageSize?: int32 = 100;
}

The Python code for this model.

class PaginatedBodyParams(PaginatedBase):
    """Parameters for pagination in the body of a request."""

The TypeScript code for this model.

export const PaginatedBodyParamsSchema = z.object({
  /** The page to return */
  page: z.number().int().min(1).nullish().default(1),

  /** The number of items to return per page */
  pageSize: z.number().int().min(1).nullish().default(100),
});

Changelog

Version	Changes	Schema
0.1.0	Added `PaginatedBodyParams` model	PaginatedBodyParams.yaml

PaginatedResultsInfo

Details about the paginated results. This model should included in the response from a paginated route.

Table

Parameter	Type	Description
page	integer	The page to return
pageSize	integer	The number of items to return per page
totalItems	integer	The total number of items across all pages
totalPages	integer	The total number of pages

Formats

A JSON example of this model.

{
  "page": 1,
  "pageSize": 20,
  "totalItems": 100,
  "totalPages": 5
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: PaginatedResultsInfo.yaml
type: object
properties:
  page:
    type: integer
    minimum: 1
    maximum: 2147483647
    examples:
      - 1
    description: Current page number (indexing starts at 1)
  pageSize:
    type: integer
    examples:
      - 20
    minimum: 1
    description: Number of items per page
  totalItems:
    type: integer
    examples:
      - 100
    description: Total number of items across all pages
  totalPages:
    type: integer
    examples:
      - 5
    description: Total number of pages
required:
  - page
  - pageSize
unevaluatedProperties:
  not: {}
description: Details about the paginated results

The TypeSpec code for this model.

/** Details about the paginated results */
@Versioning.added(CommonGrants.Versions.v0_1)
model PaginatedResultsInfo {
  /** Current page number (indexing starts at 1) */
  @example(1)
  @minValue(1)
  page: int32;

  /** Number of items per page */
  @example(20)
  @minValue(1)
  pageSize: integer;

  /** Total number of items across all pages */
  @example(100)
  totalItems?: integer;

  /** Total number of pages */
  @example(5)
  totalPages?: integer;
}

The Python code for this model.

class PaginatedResultsInfo(PaginatedBase):
    """Information about the pagination of a list."""

    total_items: int = Field(
        ...,
        alias="totalItems",
        description="The total number of items",
    )
    total_pages: int = Field(
        ...,
        alias="totalPages",
        description="The total number of pages",
    )

    model_config = {"populate_by_name": True}

The TypeScript code for this model.

export const PaginatedResultsInfoSchema = z.object({
  /** Current page number (indexing starts at 1) */
  page: z.number().int().min(1),

  /** Number of items per page (0 when the page is empty) */
  pageSize: z.number().int().min(0),

  /** Total number of items across all pages */
  totalItems: z.number().int().nullish(),

  /** Total number of pages */
  totalPages: z.number().int().nullish(),
});

Changelog

Version	Changes	Schema
0.1.0	Added `PaginatedResultsInfo` model	PaginatedResultsInfo.yaml