Paginated

Paginated

A 200 response with a paginated list of items.

Table

Parameter	Type	Description
status	integer	The HTTP status code
message	string	The message to return
items	array	Items from the current page
paginationInfo	PaginatedResultsInfo	Details about the pagination

Formats

Example

A JSON example of this model.

{
  "status": 200,
  "message": "Success",
  "items": [
    {
      "id": "123",
      "name": "Test 1"
    },
    {
      "id": "124",
      "name": "Test 2"
    }
  ],
  "paginationInfo": {
    "page": 1,
    "pageSize": 10,
    "totalItems": 25,
    "totalPages": 3
  }
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: Paginated.yaml
type: object
properties:
  items:
    type: array
    items: {}
    description: Items from the current page
  paginationInfo:
    $ref: PaginatedResultsInfo.yaml
    description: Details about the paginated results
required:
  - items
  - paginationInfo
allOf:
  - $ref: Success.yaml
unevaluatedProperties:
  not: {}
description: A 200 response with a paginated list of items

TypeSpec

The TypeSpec code for this model.

@Versioning.added(CommonGrants.Versions.v0_1)
model PaginatedBase<T> {
  /** Items from the current page */
  @pageItems
  items: T[];

  /** Details about the paginated results */
  paginationInfo: Pagination.PaginatedResultsInfo;
}

/** A 200 response with a paginated list of items of an unspecified shape
 *
 * Routes use the typed `PaginatedT<T>` variant.
 */
@doc("A 200 response with a paginated list of items")
@Versioning.added(CommonGrants.Versions.v0_1)
model Paginated extends Success {
  ...PaginatedBase<unknown>;
}

Python

The Python code for this model.

class Paginated(Success, Generic[ItemsT]):
    """Template for a response with a paginated list of items."""

    items: list[ItemsT] = Field(..., description="Items from the current page")
    pagination_info: PaginatedResultsInfo = Field(
        ...,
        description="Details about the paginated results",
        alias="paginationInfo",
    )

    model_config = {"populate_by_name": True}

TypeScript

The TypeScript code for this model.

export const PaginatedSchema = <T extends z.ZodTypeAny>(itemsSchema: T) =>
  SuccessSchema.extend({
    /** Items from the current page */
    items: z.array(itemsSchema),

    /** Details about the paginated results */
    paginationInfo: PaginatedResultsInfoSchema,
  });

Usage

Use the PaginatedT<T> template to define a 200 response with a paginated list of typed items within an API operation:

import "@common-grants/core";
import "@typespec/http";

using TypeSpec.Http;
using CommonGrants.Pagination;
using CommonGrants.Responses;

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

@summary("List test models")
@doc("Get a paginated list of test models")
@get
op listTest(...PaginatedQueryParams): PaginatedT<TestModel>;

Changelog

Version	Changes	Schema
0.1.0	Added Paginated model	Paginated.yaml