Handling Request Methods

A mobile client posts an order to /api/orders and your handler dies with SyntaxError: Unexpected token < in JSON at position 0. That "<" is the giveaway: the client sent HTML, or a form, or nothing, and request.json() tried to parse it as JSON anyway. Reading a body correctly starts with matching the reader to the content type.

The incoming argument is a standard Web Request, so every platform body method works unchanged in route handlers:

export async function POST(request: NextRequest) {
  const type = request.headers.get('content-type') ?? '';
  if (!type.includes('application/json')) {
    return apiError(415, 'unsupported_media_type', 'Send application/json');
  }
  let body: unknown;
  try {
    body = await request.json();
  } catch {
    return apiError(400, 'invalid_json', 'Body is not valid JSON');
  }
  const parsed = OrderSchema.safeParse(body);
  if (!parsed.success) {
    return apiError(422, 'validation_failed', zodIssues(parsed.error));
  }
  return NextResponse.json(await createOrder(parsed.data), { status: 201 });
}

The status codes are deliberate: 415 for the wrong media type, 400 for a body that is not even parseable, 422 for well-formed JSON that fails your schema. Each one is a distinct client bug, and distinguishing them turns a day of debugging into a glance at the status line.

Validation is not optional polish. await request.json() hands you an unknown value; anything you touch before a schema check is a bet that the client is well behaved. A safeParse-style check also lets you report every failing field at once — errors: [{ path: 'email', message: 'invalid format' }, ...] — instead of making the client fix one problem per round trip. And when the endpoint authenticates by cookie, verify the Origin header on state-changing methods: a cross-site POST arrives with the user's cookies attached, which is exactly the CSRF setup that sameSite exists to blunt.

formData() deserves one warning about scale: it buffers the entire multipart body in memory before you see a byte. Fine for an avatar; a memory incident for a gigabyte upload — and platform request-body caps (Vercel allows 4.5 MB on the Hobby plan, for instance) make large transfers fail anyway. Big files belong in a presigned object-storage upload, with your handler only recording the resulting key. The File objects you do receive expose name, type, size, and arrayBuffer(), which is everything a normal upload endpoint needs.

The trap that produces real incidents: a request body can be consumed only once. request.body is a one-shot ReadableStream — after json() reads it, a second read yields an error or an empty stream. That matters when two layers both need the payload: an auth helper wants the body for a claim check and the handler wants it for the order. The platform answer is request.clone(), which tees the stream so both copies read independently. Keep clones few — each one buffers memory — and prefer passing parsed data down instead. You will meet the clone pattern again in Verifying Webhook Signatures, where signature verification genuinely requires the untouched raw bytes alongside the parsed event.

Every handler needs to answer three questions before touching data: who is calling, from where, and what format do they expect. All three arrive in headers.

request.headers is a platform Headers object: lookups are case-insensitive, and get() returns a single comma-joined value when a header is repeated. The one exception is set-cookie, which never joins — the dedicated headers.getSetCookie() accessor returns an array, and it matters when a proxy adds a cookie of its own to the upstream response.

export async function GET(request: NextRequest) {
  const auth = request.headers.get('authorization');        // case-insensitive
  const theme  = request.cookies.get('theme')?.value;        // parsed for you
  const lang   = request.headers.get('accept-language')?.split(',')[0] ?? 'en';
  const etag   = request.headers.get('if-none-match');
  // ... 401 if auth is missing, 304 if etag matches, per-language payload otherwise
}

The authorization header is where API auth begins: clients send Authorization: Bearer <token>, you strip the scheme, and verify the token server-side — the full treatment is in Protecting Endpoints with Sessions. Note that headers are also where CORS lives: a browser calling your API from another origin must pass the preflight OPTIONS request, and your handler must echo access-control-allow-origin, access-control-allow-credentials, and the allowed headers explicitly — browsers enforce this before your GET ever runs.

Cookies come through two different doors, and interviews love the distinction:

import { cookies } from 'next/headers';

export async function POST(request: NextRequest) {
  const token = (await cookies()).get('session')?.value;
  if (!token) return apiError(401, 'no_session', 'Log in first');
  const res = NextResponse.json({ ok: true });
  res.cookies.set('last_seen', Date.now().toString(), {
    httpOnly: true, secure: true, sameSite: 'lax', path: '/', maxAge: 60 * 60 * 24 * 30,
  });
  return res;
}

In a route handler both doors read the same incoming header; the difference is mutation (cookies() allows set/delete where request.cookies never does) and consistency with pages and layouts, where only cookies() exists. When setting, always reason through the four attributes that decide security posture: httpOnly blocks script access (kills XSS token theft), secure requires HTTPS, sameSite controls cross-site sending (lax is the usual default; none requires secure), and path scopes where the cookie is sent at all.

One asymmetry worth memorizing: reading a cookie in a route handler does not by itself change the route's caching — but reading cookies() inside a page or layout opts that segment into dynamic rendering, because the output now depends on the caller.

A quick inventory of the headers worth handling deliberately: authorization for bearer tokens, content-type for your body reader, accept when clients need different representations, if-none-match if you implement ETags on expensive GETs, and an incoming x-request-id echoed into logs so a support ticket can be traced to one request. You cannot set forbidden request headers such as Host or Cookie from a handler — the platform owns them — and attempting it is a silent no-op rather than an error, which is why header bugs are so pleasant to misdiagnose.

A single /api/orders endpoint usually serves more than GET and POST. PUT replaces a resource, PATCH merges fields into it, DELETE removes it — and the method you dispatch on is the contract that tells clients which of those operations they are invoking. Export each method as its own function and share validation helpers rather than branching on request.method inside one function; the exports are the contract.

Query strings do not arrive as a props object in route handlers — parse them from the URL:

export async function GET(request: NextRequest) {
  const { searchParams } = request.nextUrl;
  const limit = Math.min(Number(searchParams.get('limit') ?? 20), 100);
  const cursor = searchParams.get('cursor');          // keyset pagination
  const status = searchParams.get('status');
  return NextResponse.json(await listOrders({ limit, cursor, status }));
}

The Math.min(..., 100) is not defensive noise: an unbounded limit turns one curious client into a denial-of-service against your database. Defaults plus hard caps belong in every list endpoint.

Now the semantics that separate careful APIs from sloppy ones:

export async function PUT(request: NextRequest, { params }) {
  const { id } = await params;
  const body = OrderSchema.parse(await request.json());   // full replacement
  return NextResponse.json(await replaceOrder(id, body)); // same body, same result on retry
}

export async function PATCH(request: NextRequest, { params }) {
  const { id } = await params;
  const body = PartialOrderSchema.parse(await request.json()); // changed fields only
  return NextResponse.json(await mergeOrder(id, body));
}

export async function DELETE(request: NextRequest, { params }) {
  const { id } = await params;
  await deleteOrder(id);
  return new NextResponse(null, { status: 204 });       // no body on success
}

PUT is idempotent — repeating it leaves the same state — while POST is not, which is why a mobile client on a flaky network can safely retry a PUT after a timeout but must ask before re-issuing a POST. PATCH has no idempotency guarantee; incrementing a counter field twice is exactly the failure the distinction exists to describe. DELETE on an already-deleted resource should return 204 again, not 404, if you want safe retries.

For creates that must survive flaky networks, the industry answer is the Idempotency-Key header: the client generates one UUID per logical operation, you atomically claim it (Redis SET key value NX EX 86400, or a unique index in Postgres) before doing any work, and a repeat with the same key returns the stored first response instead of creating a second order. One atomic statement gives you the guarantee; a check-then-insert with a race window does not.

Next.js also derives some methods for you: HEAD is served from your GET with the body stripped, and a default OPTIONS response advertises the allowed methods, so preflights for a simple same-origin API succeed without an explicit export. Write your own OPTIONS only when you need custom CORS headers — and then echo the requested origin and methods exactly, because a wildcard * cannot be combined with credentials.

Finally, the 405 contract. Next.js answers unexported methods with 405 and an Allow header automatically, but return it explicitly when the handler has a precondition — for example, refusing writes during a maintenance window:

return new NextResponse(null, {
  status: 405,
  headers: { allow: 'GET, POST', 'x-robots-tag': 'noindex' },
});

Clients and proxies route on Allow; a 405 without it is a bug report waiting to happen. Pair the method contract with a consistent error envelope from the first chapter and you have an API a stranger can integrate with from the OpenAPI description alone.