Route Handlers: bygg API-rutter i Next.js

Vad är Route Handlers?

Route Handlers är App Routers ersättning för pages/api-mappen. De låter dig definiera HTTP-endpoints direkt i filsystemet med full kontroll över request och response.

En Route Handler skapas genom att placera en route.js-fil i en mapp under app/. Filen exporterar namngivna funktioner som matchar HTTP-metoder: GET, POST, PUT, DELETE, PATCH, HEAD och OPTIONS.

app/
  api/
    anvandare/
      route.js    ← hanterar GET /api/anvandare, POST /api/anvandare

Till skillnad från pages/api kan Route Handlers ligga var som helst i app/-trädet, inte bara under api/. Det är en namnkonvention, inte ett krav. Viktigt att notera: en mapp kan inte ha både en route.js och en page.js på samma nivå.

Din första Route Handler

Skapa app/api/halsning/route.js med en enkel GET-handler:

export async function GET() {
  return Response.json({ meddelande: "Hej från servern" });
}

Response.json() är en statisk metod på den inbyggda Response-klassen och sätter automatiskt Content-Type: application/json. Du kan också skapa ett Response-objekt manuellt för mer kontroll:

export async function GET() {
  const data = { status: "ok", tidpunkt: new Date().toISOString() };

  return new Response(JSON.stringify(data), {
    status: 200,
    headers: { "Content-Type": "application/json" },
  });
}

Route Handlers körs i Edge Runtime eller Node.js-runtime beroende på konfiguration. Som standard används Node.js.

POST och request body

För att ta emot data i en POST-förfrågan använder du request.json() som returnerar ett Promise med det parsade request-bodyt.

export async function POST(request) {
  const body = await request.json();
  const { namn, epost } = body;

  if (!namn || !epost) {
    return Response.json({ fel: "Namn och e-post krävs." }, { status: 400 });
  }

  await sparaAnvandare({ namn, epost });

  return Response.json({ lyckades: true }, { status: 201 });
}

Validera alltid inkommande data på servern, oavsett vad klienten skickar. HTTP-statuskoder bör matcha vad som faktiskt sker: 201 för skapad resurs, 400 för valideringsfel, 401 för autentiseringsproblem.

Dynamiska segment

Placera en mapp med hakparenteser i sökvägen för att fånga upp dynamiska URL-delar:

app/api/inlagg/[id]/route.js  ← hanterar GET /api/inlagg/42

Params skickas som andra argument till handler-funktionen:

export async function GET(request, { params }) {
  const { id } = await params;
  const inlagg = await hamtaInlagg(id);

  if (!inlagg) {
    return Response.json({ fel: "Hittades inte." }, { status: 404 });
  }

  return Response.json(inlagg);
}

export async function DELETE(request, { params }) {
  const { id } = await params;
  await raderaInlagg(id);
  return new Response(null, { status: 204 });
}

Observera att params är ett Promise i nyare versioner av Next.js och behöver awaitas.

Middleware och headers

Du kan läsa och skriva headers direkt via request- och response-objekten.

import { headers } from "next/headers";

export async function GET(request) {
  const headersList = await headers();
  const auktorisering = headersList.get("authorization");

  if (!auktorisering?.startsWith("Bearer ")) {
    return Response.json({ fel: "Saknar token." }, { status: 401 });
  }

  const data = await hamtaSkyddadData();

  return new Response(JSON.stringify(data), {
    status: 200,
    headers: {
      "Content-Type": "application/json",
      "Cache-Control": "private, no-store",
    },
  });
}

För CORS-hantering lägger du till rätt headers i response eller konfigurerar next.config.js.

När ska du använda Route Handlers?

Route Handlers och Server Actions löser delvis överlappande problem, men de lämpar sig för olika situationer.

Välj Route Handlers när du behöver ett publikt HTTP-API som tredjepartssystem, mobilappar eller externa webhooks kan anropa. De passar också bra för streaming-responses och när du behöver explicit kontroll över HTTP-semantik som statuskoder och headers.

Välj Server Actions när mutationen sker direkt från ett formulär eller en klientkomponent i din egen applikation. Server Actions är tätare integrerade med React och ger automatisk typkontroll med TypeScript samt enklare felhantering via useActionState.

En tumregel: om det externa system ska anropa din endpoint, använd Route Handler. Om din egen React-komponent ska trigga en mutation, använd Server Action.

Sammanfattning

Route Handlers ger dig ett flexibelt API-lager direkt i Next.js utan externa bibliotek. De stödjer alla HTTP-metoder, dynamiska segment och full headers-kontroll. Kombinera dem med Server Actions för att täcka både externa API-behov och interna datamutationer.