Creating an API Route

Welcome back. In the previous lesson, you practiced exploring and understanding your project through Codex-driven inspection. Now you’re ready to build your first piece of backend functionality: a simple API route. This lesson is your first hands-on taste of how Codex can help you implement real server-side features in a structured, incremental way.

Before writing any code, you’ll first learn how Codex processes your instructions, how it changes files, and how to craft prompts that result in correct and predictable updates. That understanding will make the actual implementation smoother and help you avoid common mistakes.

Codex is deeply integrated into the filesystem of your project. This means that when you give Codex a prompt, it doesn’t just generate text—it performs file-aware reasoning.

Codex evaluates your request in several layers:

• Workspace Awareness
  Codex sees your directory structure and the contents of files you reference, allowing it to reason about imports, naming conventions, and where new code should go.

• Intent Extraction
  Codex interprets your instructions as a set of actionable changes. If you specify a file path, it treats that as the authoritative location to modify.

• Patch Generation
  Codex prepares a unified diff of the changes and shows it to you for review. Only after your approval does it apply the edits.

This means you’re always in control—Codex acts only on explicit, file-level instructions.

What Codex Can Do

• Modify code based on natural-language instructions (add, remove, refactor, rename, reorganize)
• Update or create multiple files in one prompt when asked precisely
• Automate repetitive and tedious edits
• Suggest improvements that follow modern patterns
• Show you a preview of the changes before applying them
• Make changes without specific approval (if you allow it to do so).
• Help reason about structure, correctness, and usage of Next.js APIs

What Codex Cannot Do

• Infer your intentions from vague or incomplete prompts
• Replace architectural judgment or long-term design decisions
• Execute or run the code to validate correctness
• Guarantee perfect solutions for highly complex or project-specific logic

Codex works best when you treat it like a junior teammate: give clear instructions, review its work, and apply edits intentionally.

When working with API routes in Next.js, the most reliable prompts follow a consistent structure:

• File Scope
  Always tell Codex exactly which files it may touch:

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

• Purpose
  Describe the goal clearly:

Create a GET handler that returns a simple JSON greeting.

• Requirements
  Explicitly state any constraints:

The handler must return NextResponse.json({ message: "Hello" }). Do not add extra logic or imports.

• Safety Clause (Optional but Recommended)
  Helpful in larger projects:

Do not modify any other files.

Simple inspection

Read-only request. Show me the full content of src/app/api/hello/route.ts if it exists. If not, confirm that the folder is empty. Do not modify anything.

Create the simple route

Only create or modify src/app/api/hello/route.ts. Add a GET handler that returns a static greeting JSON.

Extend with query parameters

Only edit src/app/api/hello/route.ts. Update GET to read "name" and "language" from search params and return a customized greeting.

Following this structure helps Codex produce predictable and correct results.

The Next.js App Router uses filesystem-based routing. An API route corresponds to a folder inside src/app/api, with the logic defined in a route.ts file.

For example:

• src/app/api/hello/route.ts

This maps automatically to:

• /api/hello

Each HTTP method is exported as a function:

• export async function GET() { ... }
• export async function POST() { ... }

These functions receive a NextRequest (if needed) and must return a NextResponse.

This lesson will help you build:

• A basic version of /api/hello
• An extended, parameterized version that supports name and language query params

You will use Codex to create the route file and implement the initial handler.

Your initial version will respond like this:

{
"message": "Hello from the Task Manager training"
}

Later, you’ll update the same file to support:

• ?name=Alice
• ?language=es (supports: es, fr, de, en)
• Dynamic timestamps
• A structured JSON response

Below is the final version you’ll explore through Codex.

You’ll build this incrementally with Codex—not copy/paste—so that you learn how to prompt it effectively.

// src/app/api/hello/route.ts
import { type NextRequest, NextResponse } from 'next/server';

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

  const name = searchParams.get('name');
  const language = searchParams.get('language') || 'en';
  const format = searchParams.get('format') || 'json';

  const timestamp = new Date().toISOString();

  let greeting: string;
  switch (language.toLowerCase()) {
    case 'es':
      greeting = name ? `¡Hola, ${name}!` : '¡Hola, Mundo!';
      break;
    case 'fr':
      greeting = name ? `Bonjour, ${name}!` : 'Bonjour, Monde!';
      break;
    case 'de':
      greeting = name ? `Hallo, ${name}!` : 'Hallo, Welt!';
      break;
    default:
      greeting = name ? `Hello, ${name}!` : 'Hello, World!';
  }

  const responseData = {
    message: greeting,
    timestamp,
    parameters: {
      name: name || null,
      language,
      format
    },
    endpoint: '/api/hello',
    method: 'GET',
    status: 'success'
  };

  return NextResponse.json(responseData);
}

Your project also will include a simple links to help test the route:

src/app/page.tsx

// src/app/page.tsx
import Link from 'next/link';

export default function Home() {
  return (
    <main style={{ padding: '2rem', fontFamily: 'Arial, sans-serif' }}>
      <h1>Welcome to the Next.js API Routes Demo!</h1>
      <p>Use the following endpoints to explore the API:</p>
      <ul>
        <li><Link href="/api/hello">/api/hello</Link></li>
        <li><Link href="/api/hello?name=YourName">/api/hello?name=YourName</Link></li>
        <li><Link href="/api/hello?language=es">/api/hello?language=es</Link></li>
      </ul>
    </main>
  );
}

This helps you manually verify your changes as Codex evolves the route.

In this lesson you learned:

• How Codex processes instructions and manages code changes
• What Codex is excellent at and where its limits are
• How to write precise prompts for Next.js route development
• How Next.js API routing works, including file placement and handler naming
• How to create and evolve the /api/hello route from a static response to a parameterized one

Your practice sessions will guide you through each transformation step using Codex. You’ll first build the simplest working version of the route, then layer in query parameters, more dynamic behavior, and structured JSON responses.

When you’re ready, you can proceed to the step-by-step practices.