Next.js API routes: voorbeelden van Route Handlers
Voorbeelden van Next.js Route Handlers
Next.js API routes (Route Handlers): GET, POST, auth | We.Inc
Kopieerbare voorbeelden van Next.js Route Handlers voor de App Router: GET met query params, POST met validatie, dynamische params als promise, auth-controles, CORS en webhooks.
In de App Router is een API-endpoint een route.ts-bestand binnen app, bijvoorbeeld app/api/todos/route.ts. Exporteer async functies die vernoemd zijn naar HTTP-methoden zoals GET en POST; elke functie ontvangt een Request en geeft een Response terug, meestal Response.json(). Dynamische segmenten komen binnen als een params-promise die u await. GET-handlers zijn sinds Next.js 15 standaard dynamisch.
Basis van Route Handlers
Taak
Code
JSON teruggeven
return Response.json(data, { status: 200 })
Een JSON-body lezen
const body = await request.json()
Formuliergegevens lezen
const form = await request.formData()
?q= lezen
request.nextUrl.searchParams.get("q")
Dynamisch segment
const { id } = await params
Cookies / headers
await cookies(), await headers() uit next/headers
API routes in de Pages Router gebruikten req- en res-objecten. Route Handlers gebruiken in plaats daarvan de standaard Web Request en Response, en daar struikelt iedereen over die oudere antwoorden kopieert. Hieronder staan de patronen die u voor een echte app nodig hebt, elk geschreven voor de huidige App Router, plus een kleine tester die laat zien welke statuscodes een valideerende POST hoort terug te sturen.
Vul in de tester de nep-body van het request in en kies of de aanroeper is ingelogd.
De tester voert in uw browser dezelfde validatieregels uit als het POST-voorbeeld op deze pagina.
Lees de statuscode en de JSON die terugkomen, en wijzig dan een veld om een 400, 401 of 201 te zien.
Kopieer de voorbeeldhandler en vervang de lijst in het geheugen door uw database.
Behandel elke handler als een publiek endpoint. Controleer de sessie in de handler, ook als proxy uitgelogde gebruikers al heeft doorgestuurd.
Valideer de body met een schemabibliotheek zoals Zod en stuur een 400 met veldfouten, in plaats van een foute payload een 500 te laten veroorzaken.
Een route.ts-bestand kan niet in dezelfde map staan als een page.tsx; zet API's onder app/api om ze gescheiden te houden.
Als u OPTIONS niet exporteert, beantwoordt Next.js het voor u met een Allow-header die de methoden noemt die u wel hebt geëxporteerd.
Lees bij webhooks de ruwe body met request.text() voordat u parst, want handtekeningcontroles hebben de exacte bytes nodig.
Veelgestelde vragen
Zijn Next.js API routes verouderd?
pages/api-routes werken nog steeds in de Pages Router. In de App Router is het equivalent een Route Handler, een route.ts-bestand dat Web Request- en Response-objecten gebruikt en geen bodyParser-configuratie nodig heeft.
Welke HTTP-methoden kan een route.ts exporteren?
GET, POST, PUT, PATCH, DELETE, HEAD en OPTIONS. Een methode aanroepen die u niet hebt geëxporteerd, geeft 405 Method Not Allowed terug.
Waarom moet ik params awaiten?
Sinds Next.js 15 is params in het context-argument een promise. Schrijf const { id } = await params. Het hulptype RouteContext, gegenereerd door next dev, next build of next typegen, geeft u getypeerde params op basis van het routepad.
Worden GET Route Handlers gecachet?
Standaard niet meer. Next.js 15 maakte GET-handlers dynamisch in plaats van statisch. Zet caching weer aan met export const dynamic = 'force-static' of een revalidate-waarde. Met Cache Components ingeschakeld zet u use cache in een hulpfunctie die de handler aanroept, niet in de body van de handler.
Moet ik een Route Handler of een Server Action gebruiken?
Gebruik een Server Action voor wijzigingen die door uw eigen formulieren en knoppen worden gestart. Gebruik een Route Handler als iets buiten uw React-boom de URL aanroept: een mobiele app, een webhook, een cronjob of een script van derden.
Bestandsindeling
Het mappad is de URL. app/api/todos/route.ts beantwoordt /api/todos, en app/api/todos/[id]/route.ts beantwoordt /api/todos/42. Een catch-all-map zoals [...slug] geeft een array met segmenten door.
Route Handlers delen de segmentconfiguratie met pagina's, dus dezelfde exports voor dynamic, revalidate en runtime gelden ook voor hen.
Statuscodes die clients begrijpen
Stuur 201 nadat u iets hebt aangemaakt, 400 als de invoer fout is, 401 als niemand is ingelogd, 403 als de ingelogde gebruiker geen toestemming heeft, 404 als het record niet bestaat en 405 voor niet-ondersteunde methoden. Front-ends kunnen dan op de code vertakken in plaats van fouttekst te parsen.
Geef fouten een consistente JSON-vorm, zoals { error: string, fields?: object }, zodat één fetch-helper ze allemaal kan afhandelen.
Beveiligingschecklist
Controleer de sessie, controleer of de gebruiker eigenaar is van het record dat hij wijzigt, valideer de payload, en stuur nooit geheimen of volledige gebruikersrijen terug. De officiële authenticatiegids toont dit patroon in twee stappen: een 401 bij geen sessie en een 403 bij de verkeerde rol.
Zet CORS-headers alleen op handlers die andere origins echt moeten aanroepen, en noem de specifieke origins in plaats van een sterretje zodra er cookies in het spel zijn.
Voorbeelden van Route Handlers
GET met een zoekquery
app/api/todos/route.ts. De parameter q filtert de lijst; een lege query geeft alles terug.
POST met Zod-validatie en een auth-controle
Geeft 401 terug zonder sessie, 400 met veldfouten bij een foute body, en anders 201 met het nieuwe record. getSession staat voor uw auth-bibliotheek.
Dynamisch segment met ge-awaite params
app/api/todos/[id]/route.ts. params is een promise in Next.js 15 en later.
CORS voor één vertrouwde origin
Beantwoordt de preflight van de browser en het echte request met dezelfde toegestane origin.
De handler aanroepen vanuit een Client Component
De fetch-helper leest eerst de statuscode, zodat het formulier veldfouten uit een 400 kan tonen.
API routes in de Pages Router vs Route Handlers
Zelfde taak, andere API's
pages/api/x.ts
app/api/x/route.ts
Handler
export default function handler(req, res)
export async function GET(request)
JSON versturen
res.status(200).json(data)
return Response.json(data)
Methode kiezen
if (req.method === "POST")
een aparte geëxporteerde POST-functie
Body parsen
req.body (bodyParser-configuratie)
await request.json() of request.formData()
Querystring
request.nextUrl.searchParams
POST-tester
Bewerk een JSON-body, kies of de aanroeper is ingelogd, en zie welke statuscode en welk antwoord het valideerende POST-voorbeeld zou terugsturen.
Methode
Request-body (JSON)
Aanroeper heeft een geldige sessie
Antwoord
PUT toont de 405 die Next.js stuurt voor een methode die het bestand niet exporteert.