Standardizing Collection Responses

Welcome to the final course in the path, Stabilizing Express APIs: Pagination, Versioning, and Testing! Your API already supports authentication, role-based authorization, customer ownership rules, nested comments, and explicit ticket workflows. In this lesson, you’ll make the API’s successful responses more predictable and its collection endpoint more scalable. You’ll add validated pagination, expand filtering and sorting, parameterize LIMIT and OFFSET, and return every successful resource through a consistent { data, meta } envelope. Previously, different successful routes returned different top-level shapes. Ticket collections returned raw arrays, detail routes returned raw objects, and collection totals appeared only in the X-Total-Count header. Those responses worked, but clients had to handle each endpoint differently. The new response helper creates one stable structure for collections, resources, comments, statistics, and workflow results.

Understanding the Client-Visible Migration

Earlier, the ticket collection returned a raw array: JSON[ { "id": "tkt_1001", "title": "Cannot reset password", "status": "open" } ] The stabilized API wraps that array in a success envelope: JSON{ "data": [ { "id": "tkt_1001", "title": "Cannot reset password", "status": "open" } ], "meta": { "requestId": "7aa77657-c96a-4b77-920b-e37a722d42ec", "durationMs": 8, "page": 1, "pageSize": 10, "total": 12, "totalPages": 2 } } The same outer structure now applies to a single ticket: JSON{ "data": { "id": "tkt_1001", "title": "Cannot reset password", "status": "open" }, "meta": { "requestId": "7aa77657-c96a-4b77-920b-e37a722d42ec", "durationMs": 3 } } This is a deliberate client-visible migration. Consumers must now read successful payloads from data, while contextual information belongs in meta. Error responses retain their established structure: JSON{ "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed." }, "meta": { "requestId": "7aa77657-c96a-4b77-920b-e37a722d42ec", "durationMs": 2 } } Successful deletion remains the exception: 204 No Content still has no response body.

Why Collections Need Pagination

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

As the number of tickets grows, returning every matching row becomes increasingly expensive. Large unbounded responses consume more database time, server memory, network bandwidth, and client rendering work.

Pagination divides the filtered result into manageable pages:

text

page=1&pageSize=10
page=2&pageSize=10
page=3&pageSize=10

page=1&pageSize=10
page=2&pageSize=10
page=3&pageSize=10

The offset for a page is calculated as:

text

(page - 1) × pageSize

(page - 1) × pageSize

Examples:

text

page 1, pageSize 10 → OFFSET 0
page 2, pageSize 10 → OFFSET 10
page 3, pageSize 10 → OFFSET 20

page 1, pageSize 10 → OFFSET 0
page 2, pageSize 10 → OFFSET 10
page 3, pageSize 10 → OFFSET 20

The repository still needs the total number of filtered rows so clients can calculate navigation. PostgreSQL’s window count allows the API to retrieve the current page and the full filtered total in one query.

The collection contract in src/domain/ticket.ts now includes more sort options, an assignee filter, and required pagination values.

TypeScript

export type TicketSortField =
  | "createdAt"
  | "updatedAt"
  | "priority"
  | "status";

export type SortOrder = "asc" | "desc";

export type TicketSortField =
  | "createdAt"
  | "updatedAt"
  | "priority"
  | "status";

export type SortOrder = "asc" | "desc";

createdAt sorts by when the ticket was opened.
updatedAt sorts by the most recent mutation, including updates and workflow transitions.
priority uses the ticket’s logical low-to-high ranking rather than alphabetical order.
status uses the workflow sequence open, in_progress, and closed.

The repository options combine filters, sorting, and pagination:

TypeScript

export interface TicketListOptions {
  q?: string | undefined;
  status?: TicketStatus | undefined;
  priority?: TicketPriority | undefined;
  requesterId?: string | undefined;
  assigneeId?: string | undefined;
  sortBy: TicketSortField;
  order: SortOrder;
  page: number;
  pageSize: number;
}

export interface TicketListOptions {
  q?: string | undefined;
  status?: TicketStatus | undefined;
  priority?: TicketPriority | undefined;
  requesterId?: string | undefined;
  assigneeId?: string | undefined;
  sortBy: TicketSortField;
  order: SortOrder;
  page: number;
  pageSize: number;
}

requesterId remains a server-controlled access filter for customers.
assigneeId is a client-facing optional filter that can narrow the collection to tickets assigned to a specific user.
page and pageSize are required repository inputs. The route always supplies normalized values because Zod provides defaults.
The repository does not need to parse strings or decide fallback pagination behavior.

Converting URL Strings into Numbers

Express query parameters begin as URL-derived values. A request such as:

text

GET /api/tickets?page=2&pageSize=4

GET /api/tickets?page=2&pageSize=4

does not naturally provide JavaScript numbers. The query schema in src/schemas/ticket-schemas.ts uses Zod coercion to convert valid numeric strings before repository code runs.

TypeScript

export const ticketListQuerySchema = z.object({
  q: z.string().trim().min(1).max(100).optional(),
  status: z.enum(ticketStatuses).optional(),
  priority: z.enum(ticketPriorities).optional(),
  assigneeId: z.string().trim().min(1).optional(),
  sortBy: z
    .enum(["createdAt", "updatedAt", "priority", "status"])
    .default("createdAt"),
  order: z.enum(["asc", "desc"]).default("desc"),
  page: z.coerce.number().int().min(1).default(1),
  pageSize: z.coerce.number().int().min(1).max(50).default(10),
});

export const ticketListQuerySchema = z.object({
  q: z.string().trim().min(1).max(100).optional(),
  status: z.enum(ticketStatuses).optional(),
  priority: z.enum(ticketPriorities).optional(),
  assigneeId: z.string().trim().min(1).optional(),
  sortBy: z
    .enum(["createdAt", "updatedAt", "priority", "status"])
    .default("createdAt"),
  order: z.enum(["asc", "desc"]).default("desc"),
  page: z.coerce.number().int().min(1).default(1),
  pageSize: z.coerce.number().int().min(1).max(50).default(10),
});

z.coerce.number() converts compatible query strings such as "2" into the number 2.
.int() prevents decimal page values such as 1.5.
.min(1) prevents page zero and negative pages.
pageSize is limited to a maximum of 50, preventing clients from bypassing pagination with an excessively large page.
Defaults produce page: 1 and pageSize: 10 when the client omits both parameters.
The inferred TicketListQuery contains numbers after parsing, not raw strings.

A request without pagination parameters is normalized to an object containing:

JSON

{
  "sortBy": "createdAt",
  "order": "desc",
  "page": 1,
  "pageSize": 10
}

{
  "sortBy": "createdAt",
  "order": "desc",
  "page": 1,
  "pageSize": 10
}

The same schema validates the expanded collection controls.

TypeScript

assigneeId: z.string().trim().min(1).optional(),
sortBy: z
  .enum(["createdAt", "updatedAt", "priority", "status"])
  .default("createdAt"),
order: z.enum(["asc", "desc"]).default("desc"),

assigneeId: z.string().trim().min(1).optional(),
sortBy: z
  .enum(["createdAt", "updatedAt", "priority", "status"])
  .default("createdAt"),
order: z.enum(["asc", "desc"]).default("desc"),

assigneeId is trimmed and must remain non-empty when supplied.
sortBy is restricted to fields implemented by the repository’s trusted expression map.
order remains limited to asc and desc.

Unsupported values fail before PostgreSQL runs:

text

GET /api/tickets?page=0
GET /api/tickets?pageSize=51
GET /api/tickets?page=abc
GET /api/tickets?sortBy=title

GET /api/tickets?page=0
GET /api/tickets?pageSize=51
GET /api/tickets?page=abc
GET /api/tickets?sortBy=title

Each request enters the centralized error pipeline and returns 400 VALIDATION_ERROR.

The repository in src/repositories/ticket-repository.ts keeps SQL fragments and request-derived values separate.

TypeScript

export async function listTickets(
  options: TicketListOptions,
): Promise<TicketListResult> {
  const conditions: string[] = [];
  const values: unknown[] = [];

  const addCondition = (column: string, value: unknown) => {
    values.push(value);
    conditions.push(`${column} = $${values.length}`);
  };

conditions stores trusted SQL fragments created by repository code.
values stores requester IDs, assignee IDs, enum values, search terms, and pagination values.
addCondition() appends the data first and derives the placeholder from the new array length.

The optional equality filters use that helper:

TypeScript

if (options.requesterId) {
  addCondition("requester_id", options.requesterId);
}

if (options.assigneeId) {
  addCondition("assignee_id", options.assigneeId);
}

if (options.status) {
  addCondition("status", options.status);
}

if (options.priority) {
  addCondition("priority", options.priority);
}

The column names are fixed strings owned by the repository.
Every filter value uses a numbered PostgreSQL placeholder.
The customer’s hidden requester restriction composes with visible filters such as assignee and status.

Text search remains parameterized:

TypeScript

if (options.q) {
  values.push(`%${options.q}%`);
  conditions.push(
    `(title ILIKE $${values.length} OR description ILIKE $${values.length})`,
  );
}

One wildcard value is reused for both title and description matching.

The repository joins all active filters with AND.

TypeScript

const whereClause = conditions.length > 0
  ? `WHERE ${conditions.join(" AND ")}`
  : "";

For a request containing:

text

assigneeId=usr_agent_1&status=in_progress

the query may conceptually contain:

SQL

WHERE assignee_id = $1 AND status = $2

with a separate parameter array:

TypeScript

["usr_agent_1", "in_progress"]

When a customer makes the same request, the server-controlled requester condition appears first:

SQL

WHERE requester_id = $1
  AND assignee_id = $2
  AND status = $3

Filtering occurs before counting and pagination, so both the returned rows and total describe only the permitted matching dataset.

PostgreSQL parameters can represent data values, but they cannot safely replace column names, complete expressions, or SQL keywords. Sorting therefore comes from a fixed server-owned map.

TypeScript

const sortExpressions: Record<
  TicketListOptions["sortBy"],
  string
> = {
  createdAt: "created_at",
  updatedAt: "updated_at",
  priority:
    "CASE priority " +
    "WHEN 'low' THEN 1 " +
    "WHEN 'medium' THEN 2 " +
    "WHEN 'high' THEN 3 END",
  status:
    "CASE status " +
    "WHEN 'open' THEN 1 " +
    "WHEN 'in_progress' THEN 2 " +
    "WHEN 'closed' THEN 3 END",
};

const sortExpressions: Record<
  TicketListOptions["sortBy"],
  string
> = {
  createdAt: "created_at",
  updatedAt: "updated_at",
  priority:
    "CASE priority " +
    "WHEN 'low' THEN 1 " +
    "WHEN 'medium' THEN 2 " +
    "WHEN 'high' THEN 3 END",
  status:
    "CASE status " +
    "WHEN 'open' THEN 1 " +
    "WHEN 'in_progress' THEN 2 " +
    "WHEN 'closed' THEN 3 END",
};

Timestamp fields map directly to their PostgreSQL columns.
Priority maps to a fixed CASE expression so ascending order means low, medium, then high.
Status maps to the workflow sequence rather than alphabetical order.
The request’s raw sortBy string is never inserted directly into SQL. Zod restricts it to keys supported by the map.

The direction also comes from a trusted branch:

TypeScript

const direction =
  options.order === "asc" ? "ASC" : "DESC";

const direction =
  options.order === "asc" ? "ASC" : "DESC";

Only the two known SQL keywords can be produced.

The final ORDER BY includes a deterministic tie-breaker:

SQL

ORDER BY <selected expression> <direction>, id ASC

ORDER BY <selected expression> <direction>, id ASC

The id ASC portion matters when several tickets have the same selected sort value.

Without a stable tie-breaker, rows with equal priorities or timestamps could appear in a different relative order between requests. That could cause a row to move between pages or appear more than once as the client paginates.

The ticket ID gives PostgreSQL a final predictable ordering rule.

Pagination values remain in the parameter array just like filters.

TypeScript

values.push(options.pageSize);
const limitPlaceholder = `$${values.length}`;

values.push(
  (options.page - 1) * options.pageSize,
);
const offsetPlaceholder = `$${values.length}`;

pageSize becomes the value used by LIMIT.
The calculated offset becomes the value used by OFFSET.
Both values have already passed Zod’s integer and range validation.
Neither number is interpolated directly into the SQL statement.

If the earlier filters used $1 through $3, pagination automatically continues with $4 and $5.

The repository first counts the filtered collection, then retrieves the requested page. Keeping the count separate ensures an out-of-range positive page still reports the real filtered total even when the page itself contains no rows.

TypeScript

const countResult = await query<TicketCountRow>(
  `SELECT COUNT(*)::int AS total
   FROM tickets
   ${whereClause}`,
  values,
);

const total = countResult.rows[0]?.total ?? 0;

const pageValues = [...values];
pageValues.push(options.pageSize);
const limitPlaceholder = `$${pageValues.length}`;

pageValues.push((options.page - 1) * options.pageSize);
const offsetPlaceholder = `$${pageValues.length}`;

const result = await query<TicketRow>(
  `SELECT ${ticketColumns}
   FROM tickets
   ${whereClause}
   ORDER BY
     ${sortExpressions[options.sortBy]} ${direction},
     id ASC
   LIMIT ${limitPlaceholder}
   OFFSET ${offsetPlaceholder}`,
  pageValues,
);

WHERE filters the permitted collection before pagination.
COUNT(*) OVER() calculates the total matching rows without collapsing them into one aggregate result.
LIMIT controls the maximum number of current-page rows.
OFFSET skips rows belonging to earlier pages.
The selected sort expression and direction come only from trusted application code.
All request-derived data remains in values.

The repository then separates the page data from the repeated window count:

TypeScript

return {
  items: result.rows.map(mapTicketRow),
  total: result.rows[0]?.total_count ?? 0,
};

Every returned row carries the same total_count, so reading the first row is sufficient.
If the page contains no rows, there is no first row and the fallback returns 0.
Ticket rows continue through the shared mapper, preserving camel-case properties and ISO timestamps.

COUNT(*) OVER() is available only on returned rows. When an offset moves beyond the final matching row, PostgreSQL returns no rows, so this implementation falls back to total: 0.

For normal navigation, clients use totalPages from an earlier valid page and avoid requesting pages beyond that range. The project’s current contract does not reject an out-of-range positive page number.

The important guarantee is that valid populated pages return both their current rows and the complete filtered total in one database round trip.

Standardizing Successful Responses

The reusable helper lives in src/lib/response.ts.

TypeScript

import type { Response } from "express";

function buildMeta(
  response: Response,
  extra?: Record<string, unknown>,
): Record<string, unknown> {
  const requestId =
    response.locals.requestId as string | undefined;

  const startedAt =
    response.locals.startedAt as number | undefined;

  return {
    ...(requestId ? { requestId } : {}),
    ...(startedAt
      ? { durationMs: Date.now() - startedAt }
      : {}),
    ...extra,
  };
}

import type { Response } from "express";

function buildMeta(
  response: Response,
  extra?: Record<string, unknown>,
): Record<string, unknown> {
  const requestId =
    response.locals.requestId as string | undefined;

  const startedAt =
    response.locals.startedAt as number | undefined;

  return {
    ...(requestId ? { requestId } : {}),
    ...(startedAt
      ? { durationMs: Date.now() - startedAt }
      : {}),
    ...extra,
  };
}

requestId is included only when request-context middleware supplied one.
durationMs is included only when a request start time exists.
Route-specific metadata is merged into the same object through extra.
Spreading extra last allows the caller to add fields such as pagination information.

The public helper wraps arbitrary data:

TypeScript

export function sendSuccess<T>(
  response: Response,
  data: T,
  statusCode = 200,
  meta?: Record<string, unknown>,
) {
  return response.status(statusCode).json({
    data,
    meta: buildMeta(response, meta),
  });
}

export function sendSuccess<T>(
  response: Response,
  data: T,
  statusCode = 200,
  meta?: Record<string, unknown>,
) {
  return response.status(statusCode).json({
    data,
    meta: buildMeta(response, meta),
  });
}

The generic type T allows data to be a ticket, array, comment, statistics object, or workflow result.
The default status is 200.
Creation routes can pass 201.
Every successful JSON response receives the same top-level keys.

Returning Paginated Ticket Collections

The collection route in src/routes/ticket-routes.ts combines authentication, access scoping, normalized queries, repository pagination, and response metadata.

TypeScript

ticketRoutes.route("/")
  .get(
    validateRequest({
      query: ticketListQuerySchema,
    }),
    async (_request, response) => {
      const user = getCurrentUser(response);

      const { query } =
        response.locals.validated as {
          query: TicketListQuery;
        };

      const result = await listTickets({
        ...query,
        ...(user.role === "customer"
          ? { requesterId: user.id }
          : {}),
      });

ticketRoutes.route("/")
  .get(
    validateRequest({
      query: ticketListQuerySchema,
    }),
    async (_request, response) => {
      const user = getCurrentUser(response);

      const { query } =
        response.locals.validated as {
          query: TicketListQuery;
        };

      const result = await listTickets({
        ...query,
        ...(user.role === "customer"
          ? { requesterId: user.id }
          : {}),
      });

The router-wide authentication still establishes the current user.
Zod supplies normalized filters, sorting, page, and pageSize.
Customer requests still receive the hidden requester restriction.
Agents and administrators can paginate the full permitted collection.

The route passes pagination metadata into sendSuccess():

TypeScript

sendSuccess(response, result.items, 200, {
  page: query.page,
  pageSize: query.pageSize,
  total: result.total,
  totalPages: Math.ceil(
    result.total / query.pageSize,
  ),
});

sendSuccess(response, result.items, 200, {
  page: query.page,
  pageSize: query.pageSize,
  total: result.total,
  totalPages: Math.ceil(
    result.total / query.pageSize,
  ),
});

data contains only the current page’s ticket array.
page and pageSize describe the requested page.
total describes all rows matching the filters before pagination.
totalPages is calculated from the total and page size.

The old X-Total-Count-only contract is no longer the collection’s primary metadata mechanism. Clients can read all pagination information from the response body.

The route uses:

TypeScript

Math.ceil(result.total / query.pageSize)

Math.ceil(result.total / query.pageSize)

For example:

text

total = 12
pageSize = 5

12 ÷ 5 = 2.4
Math.ceil(2.4) = 3 pages

total = 12
pageSize = 5

12 ÷ 5 = 2.4
Math.ceil(2.4) = 3 pages

When total is zero, totalPages is also zero.

The response may therefore include:

JSON

{
  "data": [],
  "meta": {
    "page": 1,
    "pageSize": 10,
    "total": 0,
    "totalPages": 0
  }
}

{
  "data": [],
  "meta": {
    "page": 1,
    "pageSize": 10,
    "total": 0,
    "totalPages": 0
  }
}

The statistics route now uses the same helper:

TypeScript

ticketRoutes.get(
  "/stats",
  authorizeRoles("agent", "admin"),
  async (_request, response) => {
    sendSuccess(
      response,
      await countTicketsByStatus(),
    );
  },
);

ticketRoutes.get(
  "/stats",
  authorizeRoles("agent", "admin"),
  async (_request, response) => {
    sendSuccess(
      response,
      await countTicketsByStatus(),
    );
  },
);

A successful response becomes:

JSON

{
  "data": {
    "open": 4,
    "inProgress": 4,
    "closed": 4
  },
  "meta": {
    "requestId": "generated-request-id",
    "durationMs": 3
  }
}

{
  "data": {
    "open": 4,
    "inProgress": 4,
    "closed": 4
  },
  "meta": {
    "requestId": "generated-request-id",
    "durationMs": 3
  }
}

Assignment uses the same response contract:

TypeScript

sendSuccess(
  response,
  await assignTicket(
    params.ticketId,
    body.assigneeId,
  ),
);

sendSuccess(
  response,
  await assignTicket(
    params.ticketId,
    body.assigneeId,
  ),
);

Closing and reopening also return their updated ticket under data.

The service and repository layers do not need to know about response envelopes. HTTP formatting remains in the route layer through one helper.

Ticket creation still returns 201 Created and a Location header.

TypeScript

.post(
  requireJson,
  validateRequest({
    body: createTicketBodySchema,
  }),
  async (request, response) => {
    const user = getCurrentUser(response);

    const { body } =
      response.locals.validated as {
        body: CreateTicketBody;
      };

    const ticket = await createTicket({
      ...body,
      requesterId: user.id,
    });

    response.setHeader(
      "Location",
      `${request.baseUrl}/${ticket.id}`,
    );

    sendSuccess(response, ticket, 201);
  },
)

The created ticket appears under data.
201 remains the response status.
request.baseUrl uses the router’s actual mount path.
If the router is later mounted under a versioned prefix, the generated Location header follows that mount automatically.

With the current mount, the header resembles:

text

Location: /api/tickets/tkt_<generated-id>

After future versioning, the same code can produce a path such as:

text

Location: /api/v1/tickets/tkt_<generated-id>

The authorized detail route returns the ticket loaded by requireTicketAccess.

TypeScript

.get(
  validateRequest({
    params: ticketIdParamsSchema,
  }),
  requireTicketAccess,
  (_request, response) => {
    sendSuccess(
      response,
      response.locals.ticket as Ticket,
    );
  },
)

.get(
  validateRequest({
    params: ticketIdParamsSchema,
  }),
  requireTicketAccess,
  (_request, response) => {
    sendSuccess(
      response,
      response.locals.ticket as Ticket,
    );
  },
)

The successful ticket is now under data, while request context appears under meta.

The generic update route follows the same contract:

TypeScript

const ticket = await updateTicket(
  params.ticketId,
  body,
);

if (!ticket) {
  throw new AppError(
    404,
    "TICKET_NOT_FOUND",
    "Ticket not found.",
  );
}

sendSuccess(response, ticket);

const ticket = await updateTicket(
  params.ticketId,
  body,
);

if (!ticket) {
  throw new AppError(
    404,
    "TICKET_NOT_FOUND",
    "Ticket not found.",
  );
}

sendSuccess(response, ticket);

Centralized error handling remains unchanged when the ticket does not exist.

The nested comment routes in src/routes/comment-routes.ts also use sendSuccess().

TypeScript

commentRoutes.route("/")
  .get(async (_request, response) => {
    const { params } =
      response.locals.validated as {
        params: TicketIdParams;
      };

    sendSuccess(
      response,
      await listComments(params.ticketId),
    );
  })

commentRoutes.route("/")
  .get(async (_request, response) => {
    const { params } =
      response.locals.validated as {
        params: TicketIdParams;
      };

    sendSuccess(
      response,
      await listComments(params.ticketId),
    );
  })

The comment collection appears under data:

JSON

{
  "data": [
    {
      "id": "cmt_1001",
      "ticketId": "tkt_1001",
      "authorId": "usr_agent_1",
      "message": "Investigating the issue.",
      "createdAt": "2025-02-01T10:00:00.000Z"
    }
  ],
  "meta": {
    "requestId": "generated-request-id",
    "durationMs": 4
  }
}

{
  "data": [
    {
      "id": "cmt_1001",
      "ticketId": "tkt_1001",
      "authorId": "usr_agent_1",
      "message": "Investigating the issue.",
      "createdAt": "2025-02-01T10:00:00.000Z"
    }
  ],
  "meta": {
    "requestId": "generated-request-id",
    "durationMs": 4
  }
}

Comment creation preserves 201:

TypeScript

sendSuccess(
  response,
  await createComment(
    params.ticketId,
    user.id,
    body.message,
  ),
  201,
);

sendSuccess(
  response,
  await createComment(
    params.ticketId,
    user.id,
    body.message,
  ),
  201,
);

The comment resource is returned under the same data key used by ticket creation and detail responses.

Successful deletion deliberately does not use sendSuccess().

TypeScript

if (!(await deleteTicket(params.ticketId))) {
  throw new AppError(
    404,
    "TICKET_NOT_FOUND",
    "Ticket not found.",
  );
}

response.status(204).send();

if (!(await deleteTicket(params.ticketId))) {
  throw new AppError(
    404,
    "TICKET_NOT_FOUND",
    "Ticket not found.",
  );
}

response.status(204).send();

HTTP 204 No Content requires an empty response body. Wrapping a success message in { data, meta } would contradict that status.

This gives the API one clear exception:

text

Successful JSON responses → { data, meta }
Successful deletion       → 204 with no body
Errors                    → { error, meta }

Successful JSON responses → { data, meta }
Successful deletion       → 204 with no body
Errors                    → { error, meta }

Set the API Simulator base URL to:

text

http://localhost:4000

http://localhost:4000

In the Authorization tab, select Bearer Token and use:

text

agent-token-1

agent-token-1

Send:

text

GET /api/tickets?page=1&pageSize=3&sortBy=updatedAt&order=desc

GET /api/tickets?page=1&pageSize=3&sortBy=updatedAt&order=desc

The response should contain at most three tickets under data.

Inspect meta and confirm it contains:

JSON

{
  "page": 1,
  "pageSize": 3,
  "total": 12,
  "totalPages": 4
}

{
  "page": 1,
  "pageSize": 3,
  "total": 12,
  "totalPages": 4
}

The exact total can change if earlier requests created or deleted tickets.

The tickets should be ordered by updatedAt descending, with id ASC providing stable ordering when timestamps match.

Add an assignee and status filter:

text

GET /api/tickets?assigneeId=usr_agent_1&status=in_progress&page=1&pageSize=3

GET /api/tickets?assigneeId=usr_agent_1&status=in_progress&page=1&pageSize=3

The repository applies the sequence conceptually as:

text

Filter by assignee and status
    ↓
Count all filtered rows
    ↓
Sort the filtered rows
    ↓
Return the requested page

Filter by assignee and status
    ↓
Count all filtered rows
    ↓
Sort the filtered rows
    ↓
Return the requested page

Every ticket in data should have:

JSON

{
  "assigneeId": "usr_agent_1",
  "status": "in_progress"
}

{
  "assigneeId": "usr_agent_1",
  "status": "in_progress"
}

The total value describes all matching tickets, while data.length describes only the current page.

Request the first page:

text

GET /api/tickets?page=1&pageSize=3&sortBy=createdAt&order=desc

GET /api/tickets?page=1&pageSize=3&sortBy=createdAt&order=desc

Then request the second:

text

GET /api/tickets?page=2&pageSize=3&sortBy=createdAt&order=desc

GET /api/tickets?page=2&pageSize=3&sortBy=createdAt&order=desc

The two responses should contain different rows. Their metadata should share the same pageSize, total, and totalPages, while page changes from 1 to 2.

The deterministic ID tie-breaker helps prevent equal creation timestamps from producing unstable page membership.

Try an excessive page size:

text

GET /api/tickets?pageSize=100

GET /api/tickets?pageSize=100

The response should be:

text

400 VALIDATION_ERROR

400 VALIDATION_ERROR

Also try:

text

GET /api/tickets?page=0
GET /api/tickets?page=abc
GET /api/tickets?pageSize=0
GET /api/tickets?pageSize=51

GET /api/tickets?page=0
GET /api/tickets?page=abc
GET /api/tickets?pageSize=0
GET /api/tickets?pageSize=51

All should fail before listTickets() reaches PostgreSQL.

Request one ticket:

text

GET /api/tickets/tkt_1001

GET /api/tickets/tkt_1001

The ticket should appear under data:

JSON

{
  "data": {
    "id": "tkt_1001",
    "title": "Cannot reset password",
    "status": "open"
  },
  "meta": {
    "requestId": "generated-request-id",
    "durationMs": 3
  }
}

{
  "data": {
    "id": "tkt_1001",
    "title": "Cannot reset password",
    "status": "open"
  },
  "meta": {
    "requestId": "generated-request-id",
    "durationMs": 3
  }
}

Request its comments:

text

GET /api/tickets/tkt_1001/comments

GET /api/tickets/tkt_1001/comments

The array should also appear under data with the same outer structure.

You can inspect statistics and a workflow action to verify that those successful responses follow the same contract.

Clients should now follow these rules:

text

Successful resource:
response.data

Successful collection:
response.data
response.meta.page
response.meta.pageSize
response.meta.total
response.meta.totalPages

Request diagnostics:
response.meta.requestId
response.meta.durationMs

Failed request:
response.error
response.meta

Successful deletion:
no response body

Successful resource:
response.data

Successful collection:
response.data
response.meta.page
response.meta.pageSize
response.meta.total
response.meta.totalPages

Request diagnostics:
response.meta.requestId
response.meta.durationMs

Failed request:
response.error
response.meta

Successful deletion:
no response body

This consistency reduces endpoint-specific parsing and prepares the API for versioning and integration testing.

You’ve started stabilizing the API by adding bounded pagination and one standard success envelope.

Zod now converts URL strings into validated numeric page and pageSize values, supports assignee filtering, and restricts sorting to trusted fields. The repository combines parameterized filters, fixed sort expressions, stable tie-breaking, parameterized LIMIT and OFFSET, and COUNT(*) OVER() in one PostgreSQL query.

The reusable sendSuccess() helper wraps ticket arrays, ticket resources, comments, statistics, creation results, updates, and workflow actions in { data, meta }. Collection metadata now includes page information and totals directly in the response body, while deletion correctly remains a bodyless 204.

With a predictable collection contract and consistent successful responses, the API is ready for versioned routing, readiness checks, and automated integration testing.