Validation and Response Helpers

Validation + Consistent Responses: Making Your API Feel “Professional”

Welcome back! In this lesson, we’ll take your Task Manager API from “it works” to “it’s predictable and safe to use.” That means validating everything that comes in (so bad input can’t sneak through) and standardizing everything that goes out (so every client knows exactly what shape to expect). You’ll do this in a very “Codex CLI” way: small, targeted prompts that touch a couple of files at a time, with clear rules about behavior and response shape. By the end, your /api/tasks, /api/tasks/[id], and /api/tasks/filter endpoints will all speak the same JSON “language,” and they’ll reject invalid requests with helpful, consistent error payloads.

Previously…

In the previous lesson, you focused on polishing the API surface: introducing response helpers and refactoring routes to use them so every response had a consistent envelope. Now we’ll build on that foundation by adding Zod -powered request validation (instead of ad-hoc checks), and we’ll apply it across create/update flows so the backend is just as strict and predictable as the response format.

How we’ll use Codex CLI in this lesson

The key habit is to treat Codex like a teammate who needs constraints. For each change, you’ll give a prompt that: lists the exact files Codex may modify, describes the exact response shape and status codes, and explicitly says “don’t touch anything else.” For example: Codex, modify only src/lib/validation/taskSchemas.ts . Implement Zod schemas for task create/update: createTaskSchema, putTaskSchema, and patchTaskSchema . Keep the field rules: title / content required non-empty strings, completed default false, dueDate optional but must parse as a date string. Do not modify any other files. Show the full updated file. That “only these files” pattern is what keeps vibe coding from turning into mystery refactors.

Defining task rules once with Zod schemas

Validation is easiest to maintain when you define it one time, then reuse it everywhere. In this project, that “single source of truth” for task input validation lives in src/lib/validation/taskSchemas.ts . TypeScript // src/lib/validation/taskSchemas.ts import { z } from 'zod'; export const createTaskSchema = z.object({title: z.string().min(1, "'title' must be a non-empty string."), content: z.string().min(1, "'content' must be a non-empty string."), completed: z.boolean().default(false), dueDate: z.string().optional().refine((val) => val === undefined || !Number.isNaN(Date.parse(val)), { message: "'dueDate' must be a valid date string." }),}); // PUT: All fields required export const putTaskSchema = createTaskSchema; // PATCH: All fields optional export const patchTaskSchema = createTaskSchema.partial(); createTaskSchema defines the exact shape your API accepts when creating tasks: required title / content, a boolean completed (defaulting to false), and an optional dueDate that must be parseable as a date string. This keeps your API strict without needing repetitive “if/else validation” in every route. .refine(...) is doing the “date sanity check.” Instead of trusting that a string looks like a date, it ensures Date.parse(...) doesn’t fail—so "not-a-date" can’t slip in and break later logic. putTaskSchema and patchTaskSchema share the same base rules, but express different update semantics: PUT requires the full object, while PATCH makes every field optional via .partial() . This mirrors common REST expectations and keeps your update logic consistent.

Join the 1M+ learners on CodeSignal

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

Validating creates in the collection route

Now we apply those building blocks to the API. The collection route lives at src/app/api/tasks/route.ts, and it handles:

GET /api/tasks (list tasks)
POST /api/tasks (create task, with Zod validation)

This route also opts out of caching with export const dynamic = 'force-dynamic', which is important for endpoints backed by changing data.

TypeScript

// src/app/api/tasks/route.ts
export const dynamic = 'force-dynamic';
import { NextRequest } from 'next/server';
import { getAllTasks, createTask } from '@/lib/services/taskService';
import { createTaskSchema } from '@/lib/validation/taskSchemas';
import { createErrorResponse, createSuccessResponse } from '@/lib/responses';

export async function GET() {
  // Ensure we resolve the tasks before responding
  const tasks = await getAllTasks();
  return createSuccessResponse(tasks);
}

export async function POST(req: NextRequest) {
  const body = await req.json();
  const parsed = createTaskSchema.safeParse(body);

  if (!parsed.success) {
    return createErrorResponse(parsed.error.format(), 400);
  }

  const newTask = await createTask(parsed.data);

  return createSuccessResponse(newTask, 201);
}

// src/app/api/tasks/route.ts
export const dynamic = 'force-dynamic';
import { NextRequest } from 'next/server';
import { getAllTasks, createTask } from '@/lib/services/taskService';
import { createTaskSchema } from '@/lib/validation/taskSchemas';
import { createErrorResponse, createSuccessResponse } from '@/lib/responses';

export async function GET() {
  // Ensure we resolve the tasks before responding
  const tasks = await getAllTasks();
  return createSuccessResponse(tasks);
}

export async function POST(req: NextRequest) {
  const body = await req.json();
  const parsed = createTaskSchema.safeParse(body);

  if (!parsed.success) {
    return createErrorResponse(parsed.error.format(), 400);
  }

  const newTask = await createTask(parsed.data);

  return createSuccessResponse(newTask, 201);
}

GET awaits getAllTasks() before returning, ensuring the response contains actual task data (not a pending Promise). It then wraps that array in createSuccessResponse(...) so the client always gets { data: [...], meta: ... }.
POST validates the request body using safeParse, which avoids throwing and instead returns a { success: boolean } result. That makes the happy-path clean, and it makes invalid input easy to convert into a 400 with a structured error payload.

When validation fails, the route returns parsed.error.format() inside the error field. That gives clients field-specific error details (great for UIs) while still preserving the same { error, meta } envelope.

Validating updates and handling route params safely

Item routes are where APIs often get messy—different status codes, different “not found” behaviors, and inconsistent update rules. In this project, src/app/api/tasks/[id]/route.ts keeps it consistent and also includes a small helper to safely resolve params, even if they arrive as a Promise in some runtimes.

TypeScript

// src/app/api/tasks/[id]/route.ts
export const dynamic = 'force-dynamic';
import { NextRequest, NextResponse } from 'next/server';
import { getTaskById, updateTask, deleteTask } from '@/lib/services/taskService';
import { putTaskSchema, patchTaskSchema } from '@/lib/validation/taskSchemas';
import { createErrorResponse, createSuccessResponse } from '@/lib/responses';

type Params = { id: string };

async function resolveParams(params: Params | Promise<Params>): Promise<Params> {
  if (params && typeof (params as any).then === 'function') {
    return await (params as Promise<Params>);
  }
  return params as Params;
}

export async function GET(_: NextRequest, ctx: { params: Params | Promise<Params> }) {
  const { id: rawId } = await resolveParams(ctx.params);
  const id = parseInt(rawId);
  const task = await getTaskById(id);
  if (!task) return createErrorResponse('Task not found', 404);
  return createSuccessResponse(task);
}

export async function PUT(req: NextRequest, ctx: { params: Params | Promise<Params> }) {
  const { id: rawId } = await resolveParams(ctx.params);
  const id = parseInt(rawId);
  const body = await req.json();
  const parsed = putTaskSchema.safeParse(body);

  if (!parsed.success) return createErrorResponse(parsed.error.format(), 400);
  const updated = await updateTask(id, parsed.data);
  if (!updated) return createErrorResponse('Task not found', 404);

  return createSuccessResponse(updated);
}

// src/app/api/tasks/[id]/route.ts
export const dynamic = 'force-dynamic';
import { NextRequest, NextResponse } from 'next/server';
import { getTaskById, updateTask, deleteTask } from '@/lib/services/taskService';
import { putTaskSchema, patchTaskSchema } from '@/lib/validation/taskSchemas';
import { createErrorResponse, createSuccessResponse } from '@/lib/responses';

type Params = { id: string };

async function resolveParams(params: Params | Promise<Params>): Promise<Params> {
  if (params && typeof (params as any).then === 'function') {
    return await (params as Promise<Params>);
  }
  return params as Params;
}

export async function GET(_: NextRequest, ctx: { params: Params | Promise<Params> }) {
  const { id: rawId } = await resolveParams(ctx.params);
  const id = parseInt(rawId);
  const task = await getTaskById(id);
  if (!task) return createErrorResponse('Task not found', 404);
  return createSuccessResponse(task);
}

export async function PUT(req: NextRequest, ctx: { params: Params | Promise<Params> }) {
  const { id: rawId } = await resolveParams(ctx.params);
  const id = parseInt(rawId);
  const body = await req.json();
  const parsed = putTaskSchema.safeParse(body);

  if (!parsed.success) return createErrorResponse(parsed.error.format(), 400);
  const updated = await updateTask(id, parsed.data);
  if (!updated) return createErrorResponse('Task not found', 404);

  return createSuccessResponse(updated);
}

resolveParams(...) is a small “defensive programming” helper: it treats params as either a plain object or a Promise and normalizes it to a concrete { id }. This keeps the handler logic stable even if the framework changes how it provides route context.
GET converts the route id to a number and asks the service layer for the task. If it’s missing, the route returns a clean 404 using the standard error envelope, so clients can handle “not found” uniformly.
PUT uses putTaskSchema (all fields required) and returns a 400 with formatted Zod errors if the body doesn’t match. If validation passes but the record doesn’t exist, it returns 404, clearly separating “bad input” from “missing resource.”

The same pattern continues for PATCH (with patchTaskSchema) and DELETE (returning 204 with no JSON body).

Validating query parameters in the filter route

One more common pitfall: query params are strings, and they’re easy to mishandle. The filter route at src/app/api/tasks/filter/route.ts validates the query param strictly and still uses the same response helpers.

TypeScript

// src/app/api/tasks/filter/route.ts
export const dynamic = 'force-dynamic';
import { NextRequest } from 'next/server';
import { filterTasksByStatus } from '@/lib/services/taskService';
import { createErrorResponse, createSuccessResponse } from '@/lib/responses';

export async function GET(request: NextRequest) {
  const completedParam = request.nextUrl.searchParams.get('completed');
  if (completedParam === null) {
    return createErrorResponse("'completed' query parameter is required", 400);
  }
  if (completedParam !== 'true' && completedParam !== 'false') {
    return createErrorResponse("'completed' must be 'true' or 'false'", 400);
  }
  const completed = completedParam === 'true';
  const tasks = await filterTasksByStatus(completed);
  return createSuccessResponse(tasks);
}

// src/app/api/tasks/filter/route.ts
export const dynamic = 'force-dynamic';
import { NextRequest } from 'next/server';
import { filterTasksByStatus } from '@/lib/services/taskService';
import { createErrorResponse, createSuccessResponse } from '@/lib/responses';

export async function GET(request: NextRequest) {
  const completedParam = request.nextUrl.searchParams.get('completed');
  if (completedParam === null) {
    return createErrorResponse("'completed' query parameter is required", 400);
  }
  if (completedParam !== 'true' && completedParam !== 'false') {
    return createErrorResponse("'completed' must be 'true' or 'false'", 400);
  }
  const completed = completedParam === 'true';
  const tasks = await filterTasksByStatus(completed);
  return createSuccessResponse(tasks);
}

The handler enforces that completed is present and only allows 'true' or 'false'. This is intentionally strict—without it, clients could accidentally send completed=maybe and get confusing behavior.
The conversion to boolean happens after validation, so downstream code can treat completed as a real boolean and avoid defensive checks everywhere else.
Even though this endpoint is “different” (query-based filtering), it still returns the same success/error envelope, so client code stays simple.

Validation + Consistent Responses: Making Your API Feel “Professional”

Previously…

How we’ll use Codex CLI in this lesson

Defining task rules once with Zod schemas

Join the 1M+ learners on CodeSignal

Standardizing success + error payloads with response helpers

Validating creates in the collection route

Codex CLI prompt you’d use for this file

Validating updates and handling route params safely

Validating query parameters in the filter route

Recap: what you now have (and why it matters)