Building Products API

Products API: Listing, Search, Pagination, and Create

Welcome! 👋 In this lesson, we’ll turn the “products” backend into a real, usable API endpoint that a frontend (or your Playground UI) can rely on. You’ll see how Next.js Route Handlers act as thin HTTP “controllers” that parse requests and delegate real work to the service layer . We’ll focus specifically on two behaviors: listing products (with optional search and pagination) and creating a product (with validation and conflict handling). By the end, you’ll be able to trace a request from the route handler \to service \to repository/database (and back) and understand why each layer has a clear job.

The Products collection endpoint

In REST terms, /api/products represents a collection resource : A GET request asks: “Give me a list of products” (optionally filtered and paginated). A POST request says: “Create a new product in this collection.” In this codebase, the route handler is responsible for the HTTP mechanics (reading query params, parsing JSON, returning status codes), while business rules and defaults live in the service layer. That division keeps your API easier to extend later (for example, when you add /api/products/:id endpoints).

Route handler overview: src/app/api/products/route.ts

This file is the entry point for /api/products . It exports functions named after HTTP methods (GET, POST), which Next.js automatically wires up to incoming requests. This first chunk shows what the route handler depends on. You’ll notice it doesn’t import repositories or SQL—routes talk to services, not directly to the database. TypeScript import { NextRequest } from "next/server"; import { error, success } from "@/lib/http/response"; import {createProductService, listProducts, validateCreateProduct,} from "@/lib/services/productsService"; // IMPORTANT: this file must exist in your repo at src/lib/db/errors.ts import { isPostgresError, pgErrorToApiError } from "@/lib/db/errors"; import { NextRequest } from "next/server"; import { error, success } from "@/lib/http/response"; import {createProductService, listProducts, validateCreateProduct,} from "@/lib/services/productsService"; // IMPORTANT: this file must exist in your repo at src/lib/db/errors.ts import { isPostgresError, pgErrorToApiError } from "@/lib/db/errors"; NextRequest is the Next.js request type used in Route Handlers. It gives you the request URL, headers, and body helpers like req.json() . success() and error() come from src/lib/http/response and ensure every response follows the same envelope shape (so clients don’t need special-case parsing). listProducts, validateCreateProduct, and createProductService live in src/lib/services/productsService.ts . The route’s job is to call these and translate the result into HTTP responses. isPostgresError and pgErrorToApiError allow the route to treat database-specific errors as structured API errors (instead of returning a generic 500 every time something DB-related goes wrong).

Join the 1M+ learners on CodeSignal

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

TypeScript

import { NextRequest } from "next/server";

import { error, success } from "@/lib/http/response";
import {
  createProductService,
  listProducts,
  validateCreateProduct,
} from "@/lib/services/productsService";

// IMPORTANT: this file must exist in your repo at src/lib/db/errors.ts
import { isPostgresError, pgErrorToApiError } from "@/lib/db/errors";

TypeScript

export async function GET(req: NextRequest) {
  try {
    const { searchParams } = new URL(req.url);
    const query = searchParams.get("query") ?? undefined;
    const page = searchParams.get("page")
      ? Number(searchParams.get("page"))
      : undefined;
    const pageSize = searchParams.get("pageSize")
      ? Number(searchParams.get("pageSize"))
      : undefined;

export async function GET(req: NextRequest) {
  try {
    const { searchParams } = new URL(req.url);
    const query = searchParams.get("query") ?? undefined;
    const page = searchParams.get("page")
      ? Number(searchParams.get("page"))
      : undefined;
    const pageSize = searchParams.get("pageSize")
      ? Number(searchParams.get("pageSize"))
      : undefined;

TypeScript

    const products = await listProducts({ query, page, pageSize });
    return success(products);
  } catch (e: unknown) {
    const message = (e as Error).message || "Internal error";
    return error("INTERNAL_ERROR", message, undefined, 500);
  }
}

    const products = await listProducts({ query, page, pageSize });
    return success(products);
  } catch (e: unknown) {
    const message = (e as Error).message || "Internal error";
    return error("INTERNAL_ERROR", message, undefined, 500);
  }
}

TypeScript

export async function listProducts(params: {
  query?: string;
  page?: number;
  pageSize?: number;
}): Promise<ServiceResult<Product[]>> {
  try {
    const page = params.page && params.page > 0 ? params.page : 1;
    const pageSize =
      params.pageSize && params.pageSize > 0 ? Math.min(params.pageSize, 100) : 20;

    const products = await searchProducts({ query: params.query, page, pageSize });
    return ok(products);
  } catch (e: unknown) {
    return handleException(e);
  }
}

export async function listProducts(params: {
  query?: string;
  page?: number;
  pageSize?: number;
}): Promise<ServiceResult<Product[]>> {
  try {
    const page = params.page && params.page > 0 ? params.page : 1;
    const pageSize =
      params.pageSize && params.pageSize > 0 ? Math.min(params.pageSize, 100) : 20;

    const products = await searchProducts({ query: params.query, page, pageSize });
    return ok(products);
  } catch (e: unknown) {
    return handleException(e);
  }
}

TypeScript

function handleException(e: unknown): ServiceResult<never> {
  if (isPostgresError(e)) {
    return fail(mapPostgresError(e));
  }
  const message = (e as Error)?.message ?? "Internal error";
  return fail({ code: "INTERNAL_ERROR", message, httpStatus: 500 });
}

function handleException(e: unknown): ServiceResult<never> {
  if (isPostgresError(e)) {
    return fail(mapPostgresError(e));
  }
  const message = (e as Error)?.message ?? "Internal error";
  return fail({ code: "INTERNAL_ERROR", message, httpStatus: 500 });
}

TypeScript

export async function POST(req: NextRequest) {
  try {
    const body = await req.json().catch(() => null);

    const valid = validateCreateProduct(body);
    if (!valid.ok) {
      return error("VALIDATION_ERROR", valid.message, valid.details, 400);
    }

export async function POST(req: NextRequest) {
  try {
    const body = await req.json().catch(() => null);

    const valid = validateCreateProduct(body);
    if (!valid.ok) {
      return error("VALIDATION_ERROR", valid.message, valid.details, 400);
    }

TypeScript

    const created = await createProductService(valid.value);
    if (!created.ok) {
      return error("CONFLICT", created.message, undefined, 409);
    }

    return success(created.value, 201);

    const created = await createProductService(valid.value);
    if (!created.ok) {
      return error("CONFLICT", created.message, undefined, 409);
    }

    return success(created.value, 201);

TypeScript

  } catch (err: unknown) {
    if (isPostgresError(err)) {
      const apiError = pgErrorToApiError(err);
      return error(
        apiError.code,
        apiError.message,
        apiError.details,
        apiError.httpStatus
      );
    }

    const message = (err as Error)?.message || "Internal error";
    return error("INTERNAL_ERROR", message, undefined, 500);
  }
}

  } catch (err: unknown) {
    if (isPostgresError(err)) {
      const apiError = pgErrorToApiError(err);
      return error(
        apiError.code,
        apiError.message,
        apiError.details,
        apiError.httpStatus
      );
    }

    const message = (err as Error)?.message || "Internal error";
    return error("INTERNAL_ERROR", message, undefined, 500);
  }
}

TypeScript

export function validateCreateProduct(
  input: unknown
):
  | { ok: true; value: CreateProductInput }
  | { ok: false; message: string; details?: unknown } {
  const v = input as Partial<CreateProductInput>;

  if (!isString(v?.sku, { min: 1 })) return { ok: false, message: "sku required" };
  if (!isString(v?.name, { min: 1 })) return { ok: false, message: "name required" };
  if (!isInt(v?.price_cents, { min: 0 })) return { ok: false, message: "price_cents must be integer >= 0" };
  if (!isInt(v?.inventory_count, { min: 0 })) return { ok: false, message: "inventory_count must be integer >= 0" };

  const description = v.description ?? null;
  if (!(description === null || typeof description === "string")) {
    return { ok: false, message: "description must be string or null" };
  }

  if (v.currency !== undefined && !isEnum(v.currency, ["USD"] as const)) {
    return { ok: false, message: "currency must be USD" };
  }

  return {
    ok: true,
    value: {
      sku: v.sku!,
      name: v.name!,
      description,
      price_cents: v.price_cents!,
      currency: (v.currency ?? "USD") as Product["currency"],
      inventory_count: v.inventory_count!,
    },
  };
}

export function validateCreateProduct(
  input: unknown
):
  | { ok: true; value: CreateProductInput }
  | { ok: false; message: string; details?: unknown } {
  const v = input as Partial<CreateProductInput>;

  if (!isString(v?.sku, { min: 1 })) return { ok: false, message: "sku required" };
  if (!isString(v?.name, { min: 1 })) return { ok: false, message: "name required" };
  if (!isInt(v?.price_cents, { min: 0 })) return { ok: false, message: "price_cents must be integer >= 0" };
  if (!isInt(v?.inventory_count, { min: 0 })) return { ok: false, message: "inventory_count must be integer >= 0" };

  const description = v.description ?? null;
  if (!(description === null || typeof description === "string")) {
    return { ok: false, message: "description must be string or null" };
  }

  if (v.currency !== undefined && !isEnum(v.currency, ["USD"] as const)) {
    return { ok: false, message: "currency must be USD" };
  }

  return {
    ok: true,
    value: {
      sku: v.sku!,
      name: v.name!,
      description,
      price_cents: v.price_cents!,
      currency: (v.currency ?? "USD") as Product["currency"],
      inventory_count: v.inventory_count!,
    },
  };
}

TypeScript

export async function createProductService(
  input: CreateProductInput
): Promise<ServiceResult<Product>> {
  try {
    const existing = await getProductBySku(input.sku);
    if (existing) {
      return fail({ code: "CONFLICT", message: "SKU already exists", httpStatus: 409 });
    }

    const product = await createProduct({
      id: randomUUID(),
      sku: input.sku,
      name: input.name,
      description: input.description ?? null,
      price_cents: input.price_cents,
      currency: input.currency ?? "USD",
      inventory_count: input.inventory_count,
      status: "active",
    });

    return ok(product);
  } catch (e: unknown) {
    return handleException(e);
  }
}

export async function createProductService(
  input: CreateProductInput
): Promise<ServiceResult<Product>> {
  try {
    const existing = await getProductBySku(input.sku);
    if (existing) {
      return fail({ code: "CONFLICT", message: "SKU already exists", httpStatus: 409 });
    }

    const product = await createProduct({
      id: randomUUID(),
      sku: input.sku,
      name: input.name,
      description: input.description ?? null,
      price_cents: input.price_cents,
      currency: input.currency ?? "USD",
      inventory_count: input.inventory_count,
      status: "active",
    });

    return ok(product);
  } catch (e: unknown) {
    return handleException(e);
  }
}

TypeScript

export async function GET(req: NextRequest) {
  try {
    const { searchParams } = new URL(req.url);
    const query = searchParams.get("query") ?? undefined;
    const page = searchParams.get("page")
      ? Number(searchParams.get("page"))
      : undefined;
    const pageSize = searchParams.get("pageSize")
      ? Number(searchParams.get("pageSize"))
      : undefined;

TypeScript

    const products = await listProducts({ query, page, pageSize });
    return success(products);
  } catch (e: unknown) {
    const message = (e as Error).message || "Internal error";
    return error("INTERNAL_ERROR", message, undefined, 500);
  }
}

TypeScript

export async function listProducts(params: {
  query?: string;
  page?: number;
  pageSize?: number;
}): Promise<ServiceResult<Product[]>> {
  try {
    const page = params.page && params.page > 0 ? params.page : 1;
    const pageSize =
      params.pageSize && params.pageSize > 0 ? Math.min(params.pageSize, 100) : 20;

    const products = await searchProducts({ query: params.query, page, pageSize });
    return ok(products);
  } catch (e: unknown) {
    return handleException(e);
  }
}

TypeScript

function handleException(e: unknown): ServiceResult<never> {
  if (isPostgresError(e)) {
    return fail(mapPostgresError(e));
  }
  const message = (e as Error)?.message ?? "Internal error";
  return fail({ code: "INTERNAL_ERROR", message, httpStatus: 500 });
}

TypeScript

export async function POST(req: NextRequest) {
  try {
    const body = await req.json().catch(() => null);

    const valid = validateCreateProduct(body);
    if (!valid.ok) {
      return error("VALIDATION_ERROR", valid.message, valid.details, 400);
    }

TypeScript

    const created = await createProductService(valid.value);
    if (!created.ok) {
      return error("CONFLICT", created.message, undefined, 409);
    }

    return success(created.value, 201);

TypeScript

  } catch (err: unknown) {
    if (isPostgresError(err)) {
      const apiError = pgErrorToApiError(err);
      return error(
        apiError.code,
        apiError.message,
        apiError.details,
        apiError.httpStatus
      );
    }

    const message = (err as Error)?.message || "Internal error";
    return error("INTERNAL_ERROR", message, undefined, 500);
  }
}

TypeScript

export function validateCreateProduct(
  input: unknown
):
  | { ok: true; value: CreateProductInput }
  | { ok: false; message: string; details?: unknown } {
  const v = input as Partial<CreateProductInput>;

  if (!isString(v?.sku, { min: 1 })) return { ok: false, message: "sku required" };
  if (!isString(v?.name, { min: 1 })) return { ok: false, message: "name required" };
  if (!isInt(v?.price_cents, { min: 0 })) return { ok: false, message: "price_cents must be integer >= 0" };
  if (!isInt(v?.inventory_count, { min: 0 })) return { ok: false, message: "inventory_count must be integer >= 0" };

  const description = v.description ?? null;
  if (!(description === null || typeof description === "string")) {
    return { ok: false, message: "description must be string or null" };
  }

  if (v.currency !== undefined && !isEnum(v.currency, ["USD"] as const)) {
    return { ok: false, message: "currency must be USD" };
  }

  return {
    ok: true,
    value: {
      sku: v.sku!,
      name: v.name!,
      description,
      price_cents: v.price_cents!,
      currency: (v.currency ?? "USD") as Product["currency"],
      inventory_count: v.inventory_count!,
    },
  };
}

TypeScript

export async function createProductService(
  input: CreateProductInput
): Promise<ServiceResult<Product>> {
  try {
    const existing = await getProductBySku(input.sku);
    if (existing) {
      return fail({ code: "CONFLICT", message: "SKU already exists", httpStatus: 409 });
    }

    const product = await createProduct({
      id: randomUUID(),
      sku: input.sku,
      name: input.name,
      description: input.description ?? null,
      price_cents: input.price_cents,
      currency: input.currency ?? "USD",
      inventory_count: input.inventory_count,
      status: "active",
    });

    return ok(product);
  } catch (e: unknown) {
    return handleException(e);
  }
}

Products API: Listing, Search, Pagination, and Create

The Products collection endpoint

Route handler overview: src/app/api/products/route.ts

Join the 1M+ learners on CodeSignal

Implementing GET list and search: GET /api/products

Delegating to the service and returning a success envelope

Service behavior behind listing: src/lib/services/productsService.ts

How service exceptions become structured failures

Implementing POST create product: POST /api/products

Creating the product and mapping business outcomes

Mapping Postgres errors vs generic errors

The create validator in the service: validateCreateProduct

The create service: conflict-aware creation in createProductService

Recap