Building Products API

Building Products API | CodeSignal Learn

Lesson: Building Products API

Welcome! 👋 In this lesson, we’ll turn the products backend into a real, usable Products API that the app (and your Playground UI) can rely on. You’ll see how Remix loaders and actions stay intentionally thin: they handle HTTP concerns (query params, JSON parsing, status codes), then delegate real work to the service layer . We’ll focus on two core behaviors that almost every backend needs early: listing products (with optional search + pagination) and creating a product (with validation and conflict handling). By the end, you’ll be able to trace a request from route \to service \to repository \to database and understand why each layer exists.

The Products Collection Endpoint

In REST terms, /api/products is a collection resource : GET /api/products means: “Give me a list of products” (optionally filtered and paginated). POST /api/products means: “Create a new product inside this collection.” In Remix, these two operations live in the same route module: loader() handles read requests (GET). action() handles mutations (POST, PUT, DELETE, etc.). In this codebase, routes talk to services, not directly to SQL. That separation is what makes the API scalable: when you add product-by-id endpoints later, you’ll reuse the same services and repository patterns.

Route Overview: app/routes/api.products.ts

The file app/routes/api.products.ts is the entry point for /api/products . It exports both a loader and an action, and it relies on shared helpers for response envelopes and safe JSON parsing. Route dependencies: This chunk shows what the route depends on and hints at the architecture: the route imports services, not repositories. TypeScript // app/routes/api.products.ts import type { ActionFunctionArgs, LoaderFunctionArgs } from '@remix-run/node'; import { success, error, parseJson } from '@/lib/http/response'; import { listProducts, createProductService, validateCreateProduct } from '@/lib/services/productsService'; import { parseOptionalIntParam } from '@/lib/http/validation'; // app/routes/api.products.ts import type { ActionFunctionArgs, LoaderFunctionArgs } from '@remix-run/node'; import { success, error, parseJson } from '@/lib/http/response'; import { listProducts, createProductService, validateCreateProduct } from '@/lib/services/productsService'; import { parseOptionalIntParam } from '@/lib/http/validation'; LoaderFunctionArgs and ActionFunctionArgs are Remix types describing what Remix passes into loader and action . The key thing you’ll use here is the request, which is the standard Web Request . success() and error() come from src/lib/http/response.ts and guarantee that every API response uses the same envelope ({ data, meta } or { error, meta }). parseJson() safely parses request bodies for actions. Instead of throwing on invalid JSON, it returns an “ok / not ok” result so the route can respond consistently. parseOptionalIntParam() (from src/lib/http/validation.ts) handles pagination query params like page and pageSize with good messages and optional bounds. The services (listProducts, validateCreateProduct, createProductService) live in src/lib/services/productsService.ts . The route’s job is to call them and translate outcomes into HTTP responses.

Join the 1M+ learners on CodeSignal

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

Listing Products: GET /api/products in the Loader

The loader() implements listing with optional search and pagination. It supports these query parameters: query: optional search string (SKU or name matching happens deeper in the repository) page: optional page number (1-based) pageSize: optional number of results per page (capped by validation + service rules) Validating query params and calling the service: This code lives in app/routes/api.products.ts. The route validates inputs before calling the service. TypeScript// app/routes/api.products.ts export async function loader({ request }: LoaderFunctionArgs) { try { const searchParams = new URL(request.url).searchParams; const query = searchParams.get('query') ?? undefined; const page = parseOptionalIntParam(searchParams, 'page', { min: 1 }); if (!page.ok) return error('VALIDATION_ERROR', page.message, undefined, 400); const pageSize = parseOptionalIntParam(searchParams, 'pageSize', { min: 1, max: 100 }); if (!pageSize.ok) return error('VALIDATION_ERROR', pageSize.message, undefined, 400); const products = await listProducts({ query, page: page.value, pageSize: pageSize.value }); if (!products.ok) { return error(products.error.code, products.error.message, products.error.details, products.error.httpStatus); } return success(products.value); } catch (e: unknown) { const message = e instanceof Error ? e.message : 'Internal error'; return error('INTERNAL_ERROR', message, undefined, 500); } }// app/routes/api.products.ts export async function loader({ request }: LoaderFunctionArgs) { try { const searchParams = new URL(request.url).searchParams; const query = searchParams.get('query') ?? undefined; const page = parseOptionalIntParam(searchParams, 'page', { min: 1 }); if (!page.ok) return error('VALIDATION_ERROR', page.message, undefined, 400); const pageSize = parseOptionalIntParam(searchParams, 'pageSize', { min: 1, max: 100 }); if (!pageSize.ok) return error('VALIDATION_ERROR', pageSize.message, undefined, 400); const products = await listProducts({ query, page: page.value, pageSize: pageSize.value }); if (!products.ok) { return error(products.error.code, products.error.message, products.error.details, products.error.httpStatus); } return success(products.value); } catch (e: unknown) { const message = e instanceof Error ? e.message : 'Internal error'; return error('INTERNAL_ERROR', message, undefined, 500); } } new URL(request.url) is the standard way to parse a Remix Request URL and read query parameters via searchParams. parseOptionalIntParam(...) does the heavy lifting for parsing and validating numeric query params. If the param is missing, it returns { ok: true, value: undefined }, which allows the service to apply defaults. The route sets sensible bounds: page must be at least 1. pageSize must be between 1 and 100. These bounds protect your database from requests like page=0 or pageSize=100000. listProducts(...) returns a ServiceResult<Product[]>, not just an array. That means your route can reliably check .ok and either return a successful list or forward a structured error. The catch block is the final safety net: any unexpected exception becomes a consistent INTERNAL_ERROR envelope.

Service-Side Listing: Defaults, Limits, and Error Conversion

The loader delegates listing behavior to the service in src/lib/services/productsService.ts. The service applies defaults and caps, then calls the repository. The listProducts service: TypeScript// src/lib/services/productsService.ts 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); } }// src/lib/services/productsService.ts 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); } } Even though the route validates page and pageSize, the service still applies defaults. This is intentional: services are reusable, so if another route calls listProducts later, it still gets consistent behavior. page defaults to 1 and pageSize defaults to 20, which are common “reasonable defaults” for listing endpoints. Math.min(params.pageSize, 100) is a second line of defense. Even if another caller forgets to validate, the service avoids unbounded page sizes. The service delegates all data access to searchProducts(...) in the repository layer, keeping SQL out of services. Instead of throwing, the service returns ok(...) or fail(...) (wrapped in ServiceResult), which makes error handling explicit for routes. Centralized exception handling: The handleException() helper translates thrown errors into stable service failures. TypeScript// src/lib/services/productsService.ts 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 }); }// src/lib/services/productsService.ts 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 }); } If a database operation throws a Postgres-shaped error, the service maps it with mapPostgresError(...) into a stable API code and HTTP status. If the error is not Postgres-specific, the service returns an INTERNAL_ERROR failure to avoid leaking raw exceptions. This design keeps routes simpler: routes don’t need to know Postgres error codes—they just forward result.error.

Repository Listing: SQL Search + Pagination + Mapping

The repository module src/lib/repositories/productsRepo.ts owns SQL and row mapping. This is where search and pagination are implemented in SQL terms. Search with optional query + pagination: TypeScript// src/lib/repositories/productsRepo.ts export async function searchProducts(opts: { query?: string; page: number; pageSize: number }): Promise<Product[]> { const { query: q, page, pageSize } = opts; const offset = (page - 1) * pageSize; if (q && q.length > 0) { const rows = await query<ProductRow>( `SELECT * FROM products WHERE sku ILIKE $1 OR name ILIKE $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3`, [`%${q}%`, pageSize, offset] ); return rows.map(mapProductRow); } const rows = await query<ProductRow>( `SELECT * FROM products ORDER BY created_at DESC LIMIT $1 OFFSET $2`, [pageSize, offset] ); return rows.map(mapProductRow); } Pagination uses the classic LIMIT/OFFSET pattern, with offset = (page - 1) * pageSize. Search uses ILIKE (case-insensitive matching) and checks both SKU and name. The SQL uses $1, $2, $3 placeholders with a separate params array. This is important for safety and correctness (it prevents SQL injection and avoids quoting bugs). The repository always maps rows through mapProductRow, so the rest of the system only deals with the Product domain model.

Creating Products: POST /api/products in the Action

Creating is handled by the route action(). It needs to safely parse JSON, validate the body, call the create service, and map results to the correct HTTP status codes. Safe JSON parsing + validation + creation flow: This code lives in app/routes/api.products.ts. TypeScript// app/routes/api.products.ts export async function action({ request }: ActionFunctionArgs) { try { if (request.method !== 'POST') { return error('VALIDATION_ERROR', 'Method not allowed', undefined, 405); } const bodyResult = await parseJson(request); if (!bodyResult.ok) return error(bodyResult.code, bodyResult.message, undefined, 400); const valid = validateCreateProduct(bodyResult.value); if (!valid.ok) return error('VALIDATION_ERROR', valid.message, undefined, 400); const created = await createProductService(valid.value); if (!created.ok) return error(created.error.code, created.error.message, created.error.details, created.error.httpStatus); return success(created.value, 201); } catch (e: unknown) { const message = e instanceof Error ? e.message : 'Internal error'; return error('INTERNAL_ERROR', message, undefined, 500); } }// app/routes/api.products.ts export async function action({ request }: ActionFunctionArgs) { try { if (request.method !== 'POST') { return error('VALIDATION_ERROR', 'Method not allowed', undefined, 405); } const bodyResult = await parseJson(request); if (!bodyResult.ok) return error(bodyResult.code, bodyResult.message, undefined, 400); const valid = validateCreateProduct(bodyResult.value); if (!valid.ok) return error('VALIDATION_ERROR', valid.message, undefined, 400); const created = await createProductService(valid.value); if (!created.ok) return error(created.error.code, created.error.message, created.error.details, created.error.httpStatus); return success(created.value, 201); } catch (e: unknown) { const message = e instanceof Error ? e.message : 'Internal error'; return error('INTERNAL_ERROR', message, undefined, 500); } } Remix actions can handle multiple mutation methods, so this route explicitly checks request.method and returns a 405 if it’s not POST. That keeps behavior predictable. parseJson(request) is safer than calling request.json() directly because it converts malformed JSON into a structured { ok: false, code, message } result instead of throwing. validateCreateProduct(...) turns untrusted JSON into a typed CreateProductInput only if all validation checks pass. If creation succeeds, the route returns success(created.value, 201). The 201 status is important—it communicates “a resource was created,” not just “request succeeded.” If the service fails (conflict, DB error, etc.), the route forwards the service’s error code/message/status into the standard API error envelope.

Service Validation: Turning Unknown JSON into a Typed DTO

The validator validateCreateProduct lives in src/lib/services/productsService.ts. It’s your gatekeeper: it ensures the service only receives safe, typed input. validateCreateProduct: TypeScript// src/lib/services/productsService.ts 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!, }, }; }// src/lib/services/productsService.ts 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!, }, }; } The function accepts unknown because request bodies are untrusted by default. The whole point is to prove shape and types before returning a safe DTO. The checks use shared validation helpers: isString ensures required strings exist and aren’t empty. isInt ensures numbers are true integers (not floats or NaN) and meet min bounds. isEnum ensures currency is one of allowed values (USD for now). description is normalized to either string or null, which avoids “sometimes undefined, sometimes null” bugs later. On success, the validator returns a clean CreateProductInput that the create service can use without repeated checks.

Create Service: Enforcing Business Rules and Writing to the Database

The create service enforces domain rules (like unique SKU) and then inserts the product through the repository. createProductService: TypeScript// src/lib/services/productsService.ts 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); } }// src/lib/services/productsService.ts 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); } } The service checks for SKU uniqueness by calling getProductBySku. This is a business rule, so it belongs in the service layer, not in the route. If the SKU already exists, the service returns a CONFLICT failure with HTTP status 409. The route simply forwards this. The service generates the product ID using randomUUID(). This keeps ID generation server-side, which is the common approach for APIs (clients shouldn’t be responsible for IDs). The actual insert happens in the repository function createProduct(...), keeping SQL out of the service. Errors are converted through handleException, so Postgres errors become structured failures instead of raw thrown exceptions.

Repository Create and Archive: SQL for Writes

The repository contains the SQL for inserts and updates. This lesson focuses on create (and shows where archive fits into CRUD). Creating a product row: TypeScript// src/lib/repositories/productsRepo.ts export async function createProduct( row: Omit<ProductRow, 'created_at' | 'updated_at' | 'status'> & { status?: string } ): Promise<Product> { const rows = await query<ProductRow>( `INSERT INTO products (id, sku, name, description, price_cents, currency, inventory_count, status) VALUES ($1,$2,$3,$4,$5,$6,$7,COALESCE($8,'active')) RETURNING *`, [ row.id, row.sku, row.name, row.description, row.price_cents, row.currency, row.inventory_count, row.status ?? 'active', ] ); return mapProductRow(rows[0]); } INSERT INTO ... RETURNING * is a great pattern for APIs because you get the created row back immediately (including timestamps/defaults). COALESCE($8,'active') ensures status defaults to "active" even if the caller doesn’t pass one. The function returns a mapped Product domain model, not a raw row, keeping the rest of the codebase consistent. Parameters are passed as an array, which keeps the query safe and avoids string concatenation issues.

Archiving a product (part of CRUD)

TypeScript// src/lib/repositories/productsRepo.ts export async function archiveProduct(id: string): Promise<Product | null> { const rows = await query<ProductRow>( `UPDATE products SET status = 'archived', updated_at = now() WHERE id = $1 RETURNING *`, [id] ); return rows[0] ? mapProductRow(rows[0]) : null; }// src/lib/repositories/productsRepo.ts export async function archiveProduct(id: string): Promise<Product | null> { const rows = await query<ProductRow>( `UPDATE products SET status = 'archived', updated_at = now() WHERE id = $1 RETURNING *`, [id] ); return rows[0] ? mapProductRow(rows[0]) : null; } This is the “soft delete” approach: rather than deleting rows, you set status='archived'. Returning null when no row exists makes it easy for the service to return a NOT_FOUND error. This function is the basis for the “D” (delete/archive) part of CRUD, and you’ll build the corresponding route behavior in later lessons.

Building Products API

Lesson: Building Products API

The Products Collection Endpoint

Route Overview: app/routes/api.products.ts

Join the 1M+ learners on CodeSignal

Listing Products: GET /api/products in the Loader

Service-Side Listing: Defaults, Limits, and Error Conversion

Repository Listing: SQL Search + Pagination + Mapping

Creating Products: POST /api/products in the Action

Service Validation: Turning Unknown JSON into a Typed DTO

Create Service: Enforcing Business Rules and Writing to the Database

Repository Create and Archive: SQL for Writes

Archiving a product (part of CRUD)

Recap