Sorted

Sorted

A 200 response with a paginated list of sorted 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
sortInfo	SortedResultsInfo	The sort order of the items

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
  },
  "sortInfo": {
    "field": "name",
    "direction": "asc"
  }
}

JSON Schema

The JSON Schema for this model.

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

TypeSpec

The TypeSpec code for this model.

@Versioning.added(CommonGrants.Versions.v0_1)
model SortedBase<T> {
  ...PaginatedBase<T>;

  /** The sort order of the items */
  sortInfo: Sorting.SortedResultsInfo;
}

/** A paginated list of items of an unspecified shape with a sort order
 *
 * Routes use the typed `SortedT<T>` variant.
 */
@doc("A paginated list of items with a sort order")
@Versioning.added(CommonGrants.Versions.v0_1)
model Sorted extends Success {
  ...SortedBase<unknown>;
}

Python

The Python code for this model.

class Sorted(Paginated[ItemsT], Generic[ItemsT]):
    """A paginated list of items with a sort order."""

    sort_info: SortedResultsInfo = Field(
        ...,
        description="The sort order of the items",
        alias="sortInfo",
    )

    model_config = {"populate_by_name": True}

TypeScript

The TypeScript code for this model.

export const SortedSchema = <T extends z.ZodTypeAny>(itemsSchema: T) =>
  PaginatedSchema(itemsSchema).extend({
    /** The sort order of the items */
    sortInfo: SortedResultsInfoSchema,
  });

Usage

Use the SortedT<T> template to define a 200 response with a paginated list of sorted, 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): SortedT<TestModel>;

Changelog

Version	Changes	Schema
0.1.0	Added Sorted model	Sorted.yaml