API Routes in Next.js

After this lesson, you will be able to: Build REST API endpoints inside your Next.js app using the App Router's `route.ts` files, handle GET and POST requests with proper status codes, validate inputs with Zod, and call them from your client components.

API routes give your Next.js app a backend without spinning up a separate server. Create a `route.ts` file under `app/api/`, export functions named after HTTP methods, and you have endpoints, deployed to the same Vercel infrastructure as your pages, automatically. This lesson takes you from never having written an API route to building a small REST API for your own app: handle requests, validate input, return JSON with correct status codes.

Prerequisites:Server Components vs Client Components

What an API route is in Next.js

A `route.ts` file in the `app/api/` folder. Export functions named `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, those are the HTTP methods the endpoint handles. Each function receives the standard Web `Request` object and returns a `Response`. Folder name = URL segment, same as pages. `app/api/posts/route.ts` → `POST /api/posts`. `app/api/posts/[id]/route.ts` → `GET /api/posts/123`. The same file-based mental model as the App Router.

A GET route returning JSON

Simplest endpoint: query a list, return it as JSON. `NextResponse.json` sets the right Content-Type for you and is the standard helper.

python

// app/api/posts/route.ts
import { NextResponse } from "next/server";

// In real apps, this comes from a database (Supabase, Postgres via Prisma, etc.)
const posts = [
  { id: 1, title: "Hello Next.js" },
  { id: 2, title: "Why I love TypeScript" },
];

export async function GET() {
  return NextResponse.json(posts);
}

A POST route with input validation

Real APIs validate input. Zod is the standard TS-first validator, declare the shape once, get parsing AND types from it. Reject bad input with a 400, otherwise return 201 with the created resource.

python

// app/api/posts/route.ts
import { NextResponse } from "next/server";
import { z } from "zod";

const postSchema = z.object({
  title: z.string().min(1).max(200),
  body:  z.string().min(1),
});

let posts = [{ id: 1, title: "Hello", body: "..." }];
let nextId = 2;

export async function POST(request: Request) {
  const body = await request.json().catch(() => null);
  const result = postSchema.safeParse(body);
  if (!result.success) {
    return NextResponse.json(
      { error: "Invalid input", details: result.error.issues },
      { status: 400 },
    );
  }
  const post = { id: nextId++, ...result.data };
  posts.push(post);
  return NextResponse.json(post, { status: 201 });
}

Dynamic API routes

Same `[param]/` syntax as pages. The `params` object is a Promise in Next 15+, so await it.

python

// app/api/posts/[id]/route.ts
import { NextResponse } from "next/server";

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ id: string }> },
) {
  const { id } = await params;
  const post = posts.find((p) => p.id === Number(id));
  if (!post) {
    return NextResponse.json({ error: "Not found" }, { status: 404 });
  }
  return NextResponse.json(post);
}

Error handling and status codes

The wd-apis lesson covered HTTP status codes, apply them on the SERVER side now. Successful GET → 200. Successful POST that created a resource → 201. Bad input → 400. Missing auth → 401. Authenticated but forbidden → 403. Not found → 404. Server error → 500. Wrap risky operations in try/catch so a database failure returns a clean 500 instead of crashing the server.

Calling your API from a Client Component

Same `fetch` pattern as the wd-apis lesson. Use a relative URL since the API lives on the same origin.

python

"use client";
import { useState } from "react";

export function NewPostForm() {
  const [title, setTitle] = useState("");
  const [body, setBody]   = useState("");
  const [status, setStatus] = useState<"idle" | "saving" | "error" | "saved">("idle");

  async function submit(event: React.FormEvent) {
    event.preventDefault();
    setStatus("saving");
    try {
      const response = await fetch("/api/posts", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ title, body }),
      });
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      setStatus("saved");
      setTitle("");
      setBody("");
    } catch {
      setStatus("error");
    }
  }

  return (
    <form onSubmit={submit} className="space-y-3">
      <input value={title} onChange={(e) => setTitle(e.target.value)} placeholder="Title" className="w-full border p-2" />
      <textarea value={body} onChange={(e) => setBody(e.target.value)} placeholder="Body" className="w-full border p-2" />
      <button disabled={status === "saving"} className="rounded bg-slate-900 px-4 py-2 text-white">
        {status === "saving" ? "Saving..." : "Create post"}
      </button>
      {status === "error" && <p className="text-red-600">Could not save.</p>}
    </form>
  );
}

Add a DELETE endpoint

Extend `app/api/posts/[id]/route.ts` to handle a DELETE request. Remove the matching post from the array and return 204 No Content on success, 404 if the post doesn't exist. Required patterns check for the `DELETE` export, the params await, and the correct status codes.

Loading exercise…

ℹ️ Common mistakes only experienced devs catch

Five API-route traps. (1) **Putting writes in GET**, GETs must be safe and idempotent. Every cache, prefetcher, and crawler will hit them. Writes go in POST/PUT/DELETE. (2) **Trusting the request body**, always validate with Zod (or similar). Without validation, bad input crashes your handler or corrupts your data. (3) **Forgetting `await request.json()`**, `request.json()` is a Promise. Treating the result like a sync object reads `undefined`. (4) **Returning sensitive errors to the client**, stack traces in 500 responses leak internal info. Return a generic message; log the details server-side. (5) **Skipping rate limiting**, endpoints like sign-up or password-reset get abused immediately when shipped without limits. Add per-IP rate limiting before going live (Vercel KV + a sliding window is the canonical pattern).

←Server Components vs Client Components

Back to React and Next.js

Connecting Supabase: Database and Auth→