BackZurück zum Blog

APIs mit Next.js erstellen

Erfahren Sie, wie Sie APIs mit Next.js aufbauen können.

Diese Anleitung erklärt, wie Sie APIs mit Next.js erstellen können, einschließlich der Projekteinrichtung, dem Verständnis des App Routers und Route Handlern, der Handhabung mehrerer HTTP-Methoden, der Implementierung dynamischer Routen, der Erstellung wiederverwendbarer Middleware-Logik und der Entscheidung, wann eine dedizierte API-Ebene benötigt wird.

1. Erste Schritte

1.1 Next.js-App erstellen

Wenn Sie neu beginnen, können Sie ein neues Next.js-Projekt mit folgendem Befehl erstellen:

Terminal
npx create-next-app@latest --api

Hinweis: Das Flag --api fügt automatisch eine Beispiel-route.ts im app/-Ordner Ihres neuen Projekts hinzu, die zeigt, wie ein API-Endpunkt erstellt wird.

1.2 App Router vs. Pages Router

  • Pages Router: Historisch gesehen nutzte Next.js pages/api/* für APIs. Dieser Ansatz basierte auf Node.js-Request/Response-Objekten und einer Express-ähnlichen API.
  • App Router (Standard): Eingeführt in Next.js 13, nutzt der App Router vollständig die Web-Standard-Request/Response-APIs. Anstelle von pages/api/* können Sie nun route.ts oder route.js-Dateien überall im app/-Verzeichnis platzieren.

Warum wechseln? Die "Route Handler" des App Routers basieren auf den Web Platform Request/Response APIs anstelle von Node.js-spezifischen APIs. Dies vereinfacht das Lernen, reduziert Reibung und hilft, Wissen über verschiedene Tools hinweg wiederzuverwenden.

2. Warum (und wann) APIs mit Next.js erstellen?

  1. Öffentliche API für mehrere Clients

    • Sie können eine öffentliche API erstellen, die von Ihrer Next.js-Web-App, einer separaten Mobile-App oder einem Drittanbieterdienst genutzt wird. Beispielsweise könnten Sie /api/users sowohl in Ihrer React-Website als auch in einer React Native-Mobile-App abfragen.

  2. Proxy zu einem bestehenden Backend

    • Manchmal möchten Sie externe Microservices hinter einem einzigen Endpunkt verbergen oder konsolidieren. Next.js Route Handler können als Proxy oder Mittelschicht zu einem bestehenden Backend fungieren. Beispielsweise könnten Sie Anfragen abfangen, Authentifizierung handhaben, Daten transformieren und die Anfrage dann an eine Upstream-API weiterleiten.

  3. Webhooks und Integrationen

    • Wenn Sie externe Rückrufe oder Webhooks erhalten (z.B. von Stripe, GitHub, Twilio), können Sie diese mit Route Handlern verarbeiten.

  4. Benutzerdefinierte Authentifizierung

    • Wenn Sie Sessions, Tokens oder andere Authentifizierungslogik benötigen, können Sie Cookies speichern, Header lesen und mit den entsprechenden Daten in Ihrer Next.js-API-Ebene antworten.

Hinweis: Wenn Sie nur serverseitiges Daten-Fetching für Ihre eigene Next.js-App benötigen (und diese Daten nicht extern teilen müssen), könnten Server Components ausreichen, um Daten direkt während des Renderns abzurufen – keine separate API-Ebene ist erforderlich.

3. Erstellen einer API mit Route Handlern

3.1 Grundlegende Dateistruktur

Im App Router (app/) erstellen Sie einen Ordner, der Ihre Route repräsentiert, und darin eine route.ts-Datei.

Beispiel für einen Endpunkt unter /api/users:

app
└── api
    └── users
        └── route.ts

3.2 Mehrere HTTP-Methoden in einer Datei

Anders als bei den API-Routen des Pages Routers (die einen einzelnen Standard-Export hatten), können Sie mehrere Funktionen exportieren, die verschiedene HTTP-Methoden aus derselben Datei repräsentieren.

app/api/users/route.ts
export async function GET(request: Request) {
  // Beispiel: Daten aus Ihrer DB abrufen
  const users = [
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' }
  ];
  return new Response(JSON.stringify(users), {
    status: 200,
    headers: { 'Content-Type': 'application/json' }
  });
}
 
export async function POST(request: Request) {
  // Request-Body parsen
  const body = await request.json();
  const { name } = body;
 
  // z.B. Neuen Benutzer in DB einfügen
  const newUser = { id: Date.now(), name };
 
  return new Response(JSON.stringify(newUser), {
    status: 201,
    headers: { 'Content-Type': 'application/json' }
  });
}

Nun gibt eine GET-Anfrage an /api/users Ihre Benutzerliste zurück, während eine POST-Anfrage an dieselbe URL einen neuen Benutzer einfügt.

4. Arbeiten mit Web-APIs

4.1 Direkte Verwendung von Request & Response

Standardmäßig erhalten Ihre Route Handler-Methoden (GET, POST, etc.) ein standardmäßiges Request-Objekt, und Sie müssen ein standardmäßiges Response-Objekt zurückgeben.

4.2 Abfrageparameter

app/api/search/route.ts
import { NextRequest } from 'next/server';
 
export function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  const query = searchParams.get('query'); // z.B. `/api/search?query=hello`
 
  return new Response(
    JSON.stringify({ result: `Sie haben nach folgendem gesucht: ${query}` }),
    {
      headers: { 'Content-Type': 'application/json' },
    },
  );
}

4.3 Header und Cookies

app/api/auth/route.ts
import { NextRequest } from 'next/server';
import { cookies, headers } from 'next/headers';
 
export async function GET(request: NextRequest) {
  // 1. Verwendung der 'next/headers'-Helfer
  const cookieStore = await cookies();
  const token = cookieStore.get('token');
 
  const headersList = await headers();
  const referer = headersList.get('referer');
 
  // 2. Verwendung der standardmäßigen Web-APIs
  const userAgent = request.headers.get('user-agent');
 
  return new Response(JSON.stringify({ token, referer, userAgent }), {
    headers: { 'Content-Type': 'application/json' },
  });
}

Die Funktionen cookies() und headers() können hilfreich sein, wenn Sie gemeinsame Logik über anderen serverseitigen Code in Next.js wiederverwenden möchten. Sie werden feststellen, dass Next.js auch NextRequest und NextResponse bereitstellt, die die Basis-Web-APIs erweitern.

5. Dynamische Routen

Um dynamische Pfade zu erstellen (z.B. /api/users/:id), verwenden Sie Dynamische Segmente in Ihrer Ordnerstruktur:

app
└── api
    └── users
        └── [id]
            └── route.ts

Diese Datei entspricht einer URL wie /api/users/123, wobei 123 als Parameter erfasst wird.

app/api/users/[id]/route.ts
import { NextRequest } from 'next/server';
 
export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> },
) {
  const id = (await params).id;
  // z.B. Abfrage einer Datenbank nach Benutzer mit ID `id`
  return new Response(JSON.stringify({ id, name: `Benutzer ${id}` }), {
    status: 200,
    headers: { 'Content-Type': 'application/json' },
  });
}
 
export async function DELETE(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> },
) {
  const id = (await params).id;
  // z.B. Benutzer mit ID `id` in DB löschen
  return new Response(null, { status: 204 });
}

Hier gibt params.id Ihnen das dynamische Segment.

6. Next.js als Proxy oder Weiterleitungsebene nutzen

Ein häufiges Szenario ist das Proxying eines bestehenden Backend-Dienstes. Sie können Anfragen authentifizieren, Logging handhaben oder Daten transformieren, bevor sie an einen entfernten Server oder ein Backend gesendet werden:

app/api/external/route.ts
import { NextRequest } from 'next/server';
 
export async function GET(request: NextRequest) {
  const response = await fetch('https://example.com/api/data', {
    // Optional: Weiterleitung einiger Header, Hinzufügen von Auth-Tokens, etc.
    headers: { Authorization: `Bearer ${process.env.API_TOKEN}` },
  });
 
  // Antwort transformieren oder weiterleiten
  const data = await response.json();
  const transformed = { ...data, source: 'proxied-through-nextjs' };
 
  return new Response(JSON.stringify(transformed), {
    headers: { 'Content-Type': 'application/json' },
  });
}

Nun müssen Ihre Clients nur /api/external aufrufen, und Next.js übernimmt den Rest. Dies wird manchmal auch als "Backend for Frontend" oder BFF bezeichnet.

7. Gemeinsame "Middleware"-Logik erstellen

Wenn Sie dieselbe Logik (z.B. Authentifizierungsprüfungen, Logging) über mehrere Route Handler anwenden möchten, können Sie wiederverwendbare Funktionen erstellen, die Ihre Handler wrappen:

lib/with-auth.ts
import { NextRequest } from 'next/server';
 
type Handler = (req: NextRequest, context?: any) => Promise<Response>;
 
export function withAuth(handler: Handler): Handler {
  return async (req, context) => {
    const token = req.cookies.get('token')?.value;
    if (!token) {
      return new Response(JSON.stringify({ error: 'Nicht autorisiert' }), {
        status: 401,
        headers: { 'Content-Type': 'application/json' },
      });
    }
 
    // Wenn authentifiziert, den ursprünglichen Handler aufrufen
    return handler(req, context);
  };
}

Dann in Ihrem Route Handler:

app/api/secret/route.ts
import { NextRequest } from 'next/server';
import { withAuth } from '@/lib/with-auth';
 
async function secretGET(request: NextRequest) {
  return new Response(JSON.stringify({ secret: 'Hier gibt es Drachen' }), {
    headers: { 'Content-Type': 'application/json' },
  });
}
 
export const GET = withAuth(secretGET);

8. Bereitstellung und "SPA-Mode"-Überlegungen

8.1 Standard-Node.js-Bereitstellung

Die standardmäßige Next.js-Server-Bereitstellung mit next start ermöglicht Ihnen die Nutzung von Funktionen wie Route Handlern, Server Components, Middleware und mehr – während Sie dynamische, anfragezeitabhängige Informationen nutzen können.

Es ist keine zusätzliche Konfiguration erforderlich. Weitere Details finden Sie unter Bereitstellung.

8.2 SPA/Statischer Export

Next.js unterstützt auch die Ausgabe Ihrer gesamten Seite als statische Single-Page Application (SPA).

Sie können dies aktivieren, indem Sie folgendes setzen:

next.config.ts
import type { NextConfig } from 'next';
 
const nextConfig: NextConfig = {
  output: 'export',
};
 
export default nextConfig;

Im statischen Export-Modus generiert Next.js rein statisches HTML, CSS und JS. Sie können keinen serverseitigen Code ausführen (wie API-Endpunkte). Wenn Sie dennoch eine API benötigen, müssten Sie diese separat hosten (z.B. einen eigenständigen Node.js-Server).

Hinweis:

  • GET Route Handler können statisch exportiert werden, wenn sie nicht auf dynamische Anfragedaten angewiesen sind. Sie werden zu statischen Dateien in Ihrem out-Ordner.
  • Alle anderen Server-Funktionen (dynamische Anfragen, Cookies umschreiben, etc.) werden in einem reinen SPA-Export nicht unterstützt.

8.3 Bereitstellung von APIs auf Vercel

Wenn Sie Ihre Next.js-Anwendung auf Vercel bereitstellen, haben wir eine Anleitung zur Bereitstellung von APIs. Diese umfasst weitere Vercel-Funktionen wie programmatische Ratenbegrenzung (Rate-Limiting) über die Vercel Firewall. Vercel bietet auch Cron-Jobs, die häufig bei API-Ansätzen benötigt werden.

9. Wann Sie auf die Erstellung eines API-Endpunkts verzichten können

Mit den React Server Components des App Routers können Sie Daten direkt auf dem Server abrufen, ohne einen öffentlichen Endpunkt freizugeben:

app/users/page.tsx
// (Server Component)
export default async function UsersPage() {
  // Dieser Fetch läuft auf dem Server (hier wird kein Client-seitiger Code benötigt)
  const res = await fetch('https://api.example.com/users');
  const data = await res.json();
 
  return (
    <main>
      <h1>Benutzer</h1>
      <ul>
        {data.map((user: any) => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </main>
  );
}

Wenn Ihre Daten nur innerhalb Ihrer Next.js-App verwendet werden, benötigen Sie möglicherweise überhaupt keine öffentliche API.

10. Alles zusammenfügen

  1. Erstellen Sie ein neues Next.js-Projekt: npx create-next-app@latest --api.
  2. Fügen Sie Route Handler im Verzeichnis app/ hinzu (z.B. app/api/users/route.ts).
  3. Exportieren Sie HTTP-Methoden (GET, POST, PUT, DELETE, etc.) in derselben Datei.
  4. Verwenden Sie Web-Standard-APIs, um mit dem Request-Objekt zu interagieren und eine Response zurückzugeben.
  5. Erstellen Sie eine öffentliche API, wenn andere Clients Ihre Daten nutzen sollen oder um einen Backend-Service zu proxen.
  6. Rufen Sie Ihre neuen API-Routen vom Client ab (z.B. innerhalb einer Client Component oder mit fetch('/api/...')).
  7. Oder verzichten Sie ganz auf die Erstellung einer API, wenn eine Server Component einfach Daten abrufen kann.
  8. Fügen Sie ein gemeinsames "Middleware"-Muster hinzu (z.B. withAuth()) für Authentifizierung oder andere wiederkehrende Logik.
  9. Stellen Sie in einer Node.js-fähigen Umgebung für Server-Funktionen bereit oder exportieren Sie statisch, wenn Sie nur eine statische SPA benötigen.

Fazit

Die Verwendung des App Routers und der Route Handler in Next.js bietet Ihnen eine flexible, moderne Möglichkeit, APIs zu erstellen, die direkt die Web-Plattform nutzen. Sie können:

  • Eine vollständige öffentliche API erstellen, die von Web-, Mobile- oder Drittanbieter-Clients genutzt werden kann.
  • Aufrufe an bestehende externe Services proxen und anpassen.
  • Eine wiederverwendbare "Middleware"-Schicht für Authentifizierung, Protokollierung oder andere wiederkehrende Logik implementieren.
  • Anfragen dynamisch routen, indem Sie die [id]-Segment-Ordnerstruktur verwenden.

Häufig gestellte Fragen

Was ist mit Server Actions?

Sie können sich Server Actions wie automatisch generierte POST-API-Routen vorstellen, die vom Client aufgerufen werden können.

Sie sind für Mutationsoperationen wie das Erstellen, Aktualisieren oder Löschen von Daten konzipiert. Sie rufen eine Server Action wie eine normale JavaScript-Funktion auf, anstatt explizit einen fetch an eine definierte API-Route durchzuführen.

Obwohl dabei trotzdem eine Netzwerkanfrage stattfindet, müssen Sie diese nicht explizit verwalten. Der URL-Pfad wird automatisch generiert und verschlüsselt, sodass Sie nicht manuell auf eine Route wie /api/users im Browser zugreifen können.

Wenn Sie Server Actions und eine öffentliche API verwenden möchten, empfehlen wir, die Kernlogik in eine Data Access Layer (Datenzugriffsschicht) auszulagern und dieselbe Logik sowohl von der Server Action als auch von der API-Route aufzurufen.

Kann ich TypeScript mit Route Handlern verwenden?

Ja, Sie können TypeScript mit Route Handlern verwenden. Definieren Sie beispielsweise die Typen Request und Response in Ihrer route-Datei.

Erfahren Sie mehr über TypeScript mit Next.js.

Was sind die Best Practices für Authentifizierung?

Weitere Informationen finden Sie in unserer Authentifizierungsdokumentation.