Pagination

CommonBenefits routes that return collections use a 1-indexed page number and a per-page size. Routes that accept pagination as query parameters use PaginatedQueryParams; routes that take pagination in the request body use PaginatedBodyParams. The matching PaginatedResultsInfo envelope is returned in response bodies.

PaginatedQueryParams

Query parameters for paginated routes.

Property	Type	Required	Description
page	integer	No	The page to return.
pageSize	integer	No	The number of items to return per page.

Example

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

JSON Schema

$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.
description: Query parameters for paginated routes.

TypeSpec

/** Query parameters for paginated routes. */
@Versioning.added(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;
}

PaginatedBodyParams

Body parameters for paginated routes.

Property	Type	Required	Description
page	integer	No	The page to return.
pageSize	integer	No	The number of items to return per page.

Example

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

JSON Schema

$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.
description: Body parameters for paginated routes.

TypeSpec

/** Body parameters for paginated routes. */
@Versioning.added(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;
}

PaginatedResultsInfo

Details about the paginated results.

Property	Type	Required	Description
page	integer	Yes	Current page number (indexing starts at 1).
pageSize	integer	Yes	Number of items per page.
totalItems	integer	No	Total number of items across all pages.
totalPages	integer	No	Total number of pages.

Example

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

JSON Schema

$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
description: Details about the paginated results.

TypeSpec

/** Details about the paginated results. */
@Versioning.added(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;
}