Dynamic API Responses

Welcome back. Previously, you learned how to explore a Next.js project using Codex, how to inspect existing files safely, and how to guide Codex through small, controlled code changes. In this lesson, you’ll take your first real steps toward building the User CRUD Playground—a small, self-contained project that demonstrates how to create dynamic API endpoints, handle user input, build CRUD logic, and connect everything to a simple UI.

This unit focuses entirely on building a complete users mini-app, so you gain confidence with:

• Next.js API route patterns
• Reading query parameters and route parameters
• Handling request bodies
• Returning structured JSON
• Using Codex correctly to build and evolve the backend

Once you have mastered these fundamentals, later courses will shift your skills toward architecting the full Task Manager application.

By the end of this lesson, you will know how to:

• Make a Next.js route respond dynamically to user input
• Read query parameters and route parameters using NextRequest
• Write controlled prompts telling Codex exactly how to update your users API routes
• Begin shaping the foundational behavior of your user CRUD app

This entire unit is structured as a guided mini-project. You’ll gradually build out:

• A /api/users route for listing and creating users
• A /api/users/[id] route for showing, updating, and deleting a single user
• Input validation and structured JSON responses
• A small UI playground where you can test all CRUD operations interactively

All of it implemented through precise, well-scoped Codex prompts.

The practices build up in difficulty, starting with query-based behavior and progressing toward fully persistent updates within the session.

This lesson focuses on the first step: making your users API interactive using query parameters and route parameters.

The Next.js App Router uses a filesystem-based API routing system. Every folder under src/app/api becomes a segment in the endpoint URL.

For your users API, the structure looks like this:

src/app/api/users/route.ts    ->  /api/users
src/app/api/users/[id]/route.ts ->   /api/users/:id

Each route.ts file exports HTTP method handlers:

export async function GET() { … }
export async function POST() { … }
export async function PUT() { … }
export async function DELETE() { … }

The App Router automatically matches:

• Query parameters through request.nextUrl.searchParams
• Route parameters (like [id]) through the second argument:

export async function GET(request, { params }) { … }

Understanding this folder structure and handler pattern is essential for your CRUD work.

Codex does not “guess” what to change. It follows a very disciplined pipeline:

• Workspace awareness
  Codex reads only the files you reference, and understands directory layout and imports.

• Instruction interpretation
  It turns your natural language request into a set of file-specific actions.

• Patch generation
  Codex shows a diff of every proposed change; you must approve it.

This means you control every transformation. Codex is powerful, but only when guided clearly.

Because you’ll implement a complete users CRUD system, your prompts must be very precise. Here’s the recommended structure:

• Specify the exact file(s) Codex may modify

Only modify src/app/api/users/route.ts.

• State the purpose

Add a GET handler that reads optional "limit" and "search" query parameters.

• State the behavior clearly

If "search" is provided, filter users by name (case-insensitive).
If "limit" is provided, return only the first N users.

• List constraints

Do not modify any other files.
Do not add new fields to the user objects.

• Ask for the full file output

Show the complete final file content.

Implementing GET /api/users

Codex, modify only src/app/api/users/route.ts.
Implement a GET handler that returns all users from an in-memory array.
Add optional "search" and "limit" query parameters.
Return JSON via NextResponse.json.
Show the full final file.

Implementing GET /api/users/[id]

Codex, modify only src/app/api/users/[id]/route.ts.
Add a GET handler that reads the "id" route parameter, finds the matching user,
and returns 404 JSON if not found. Use NextResponse.json for both cases.
Show the final file.

These tightly scoped prompts match exactly how you’ll progress through each practice of your CRUD unit.

Before we implement full CRUD, you’ll first give your /api/users route the ability to handle incoming parameters. This may include:

• Searching by name
• Limiting results
• Filtering by fields like role or age
• Returning structured JSON objects with metadata

A typical pattern looks like:

import { type NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;

  const search = searchParams.get('search');
  const limit = Number(searchParams.get('limit')) || null;

  let results = USERS; // your in-memory array

  if (search) {
    results = results.filter(u =>
      u.name.toLowerCase().includes(search.toLowerCase())
    );
  }

  if (limit) {
    results = results.slice(0, limit);
  }

  return NextResponse.json({ users: results });
}

This lays the groundwork for later practices like:

• POST: creating new users
• PUT: updating a user
• DELETE: removing a user
• Handling invalid data
• Responding with consistent JSON schemas

All of these steps are completed via Codex prompting, not manual typing.

As the project evolves, your [id] route will look something like:

import { type NextRequest, NextResponse } from 'next/server';

export async function GET(_: NextRequest, { params }: { params: { id: string } }) {
  const id = Number(params.id);
  const user = USERS.find(u => u.id === id);

  if (!user) {
    return NextResponse.json({ error: 'User not found' }, { status: 404 });
  }

  return NextResponse.json({ user });
}

Again—Codex will build this for you based on your prompts.

Your job is to carefully define the transformation.

Later in this unit, you’ll create a basic UI that calls all your users API endpoints:

• Create user
• View all users
• Edit user
• Delete user
• Filter/search users

This UI is intentionally minimal. It’s simply a playground to help you test and visualize your users CRUD backend.

Once you complete this unit, the next courses will shift your skills toward building the Task Manager app, where you will apply everything you learned here on a more robust codebase and architecture.

In this lesson, you learned:

• How Next.js API routes handle query params and route params
• How to write precise Codex prompts tailored for user CRUD development
• How Codex interprets, generates, and applies changes
• How your /api/users and /api/users/[id] routes will evolve in stages
• How this unit prepares you to build a complete mini user CRUD application

Your next practices will guide you through implementing each part of the users API using Codex—starting with basic filtering and lookup routes, and ending with a complete CRUD system plus an interactive UI playground.

When you're ready, continue to the practice steps and begin evolving your users API one prompt at a time.