REST API mit Claude Code erstellen | Praxisleitfaden für Einsteiger

„Ich weiß nicht, wo ich mit REST APIs anfangen soll” — genau so ging es mir am Anfang auch.

Dokumentationen lesen fühlte sich zu abstrakt an. Ich wusste nicht, was ich eigentlich bauen sollte. Dann fing ich an, Claude Code zu benutzen, und erkannte: „Zuerst etwas zum Laufen bringen und dabei lernen” ist der schnellste Ansatz.

In diesem Leitfaden gehen wir von null REST-API-Wissen bis zu einer vollständig funktionierenden API — Schritt für Schritt, gemeinsam mit Claude Code. Alle Code-Snippets sind direkt kopierbereit.

---

Was ist eine REST API? (In 3 Sätzen)

Eine REST API ist eine Konvention zur Manipulation von Ressourcen (Daten) im Web über HTTP.

Browser/App  →  HTTP-Anfrage  →  Server (API)
             ←  JSON-Antwort  ←

Für eine Benutzerverwaltungs-API sieht das so aus:

Ziel	HTTP-Methode	URL
Alle Benutzer abrufen	GET	/users
Bestimmten Benutzer abrufen	GET	/users/123
Benutzer erstellen	POST	/users
Benutzer aktualisieren	PUT	/users/123
Benutzer löschen	DELETE	/users/123

Sobald Sie das verstehen, können Sie mit Claude Code loslegen.

---

Umgebungs-Setup

Wir verwenden Hono — ein leichtgewichtiges TypeScript-Webframework. Es ist typsicherer als Express und funktioniert hervorragend mit Claude Code.

mkdir my-first-api
cd my-first-api
npm init -y
npm install hono
npm install -D typescript @types/node ts-node
npx tsc --init

Erstellen Sie src/index.ts und fragen Sie Claude Code:

claude -p "
Erstelle einen REST API Boilerplate mit Hono in src/index.ts.
- Starte den Server auf Port 3000
- Füge einen GET /health Endpunkt für Health Checks hinzu
- Gib JSON-Antworten zurück
Ausführungsbefehl: npx ts-node src/index.ts
"

Claude Code generiert in etwa das Folgende:

// src/index.ts
import { Hono } from "hono";
import { serve } from "@hono/node-server";

const app = new Hono();

app.get("/health", (c) => {
  return c.json({ status: "ok", timestamp: new Date().toISOString() });
});

serve({ fetch: app.fetch, port: 3000 }, () => {
  console.log("Server running at http://localhost:3000");
});

npx ts-node src/index.ts
# → Server running at http://localhost:3000

curl http://localhost:3000/health
# → {"status":"ok","timestamp":"2026-04-27T07:30:00.000Z"}

Hat es funktioniert? Das ist Ihr Ausgangspunkt für REST APIs.

---

Step 1: Einfaches CRUD erstellen

Als nächstes bauen wir eine API zur Verwaltung einer Todo-Liste. Fragen Sie Claude Code:

claude -p "
Füge Todo CRUD-Endpunkte zu src/index.ts hinzu.
- GET  /todos         — Alle Todos auflisten
- GET  /todos/:id     — Einzelnes Todo abrufen
- POST /todos         — Erstellen (title: string erforderlich)
- PUT  /todos/:id     — Aktualisieren (title: string)
- DELETE /todos/:id   — Löschen

Daten in einem In-Memory-Array verwalten.
Todo-Typ: { id: string, title: string, done: boolean, createdAt: string }
ID mit crypto.randomUUID() generieren
"

Generierter Code:

import { Hono } from "hono";
import { serve } from "@hono/node-server";

const app = new Hono();

// In-Memory-Datenspeicher
type Todo = { id: string; title: string; done: boolean; createdAt: string };
let todos: Todo[] = [];

// Alle Todos abrufen
app.get("/todos", (c) => c.json(todos));

// Einzelnes Todo abrufen
app.get("/todos/:id", (c) => {
  const todo = todos.find((t) => t.id === c.req.param("id"));
  if (!todo) return c.json({ error: "Not found" }, 404);
  return c.json(todo);
});

// Erstellen
app.post("/todos", async (c) => {
  const body = await c.req.json();
  if (!body.title) return c.json({ error: "title is required" }, 400);
  const todo: Todo = {
    id: crypto.randomUUID(),
    title: body.title,
    done: false,
    createdAt: new Date().toISOString(),
  };
  todos.push(todo);
  return c.json(todo, 201);
});

// Aktualisieren
app.put("/todos/:id", async (c) => {
  const idx = todos.findIndex((t) => t.id === c.req.param("id"));
  if (idx === -1) return c.json({ error: "Not found" }, 404);
  const body = await c.req.json();
  todos[idx] = { ...todos[idx], ...body };
  return c.json(todos[idx]);
});

// Löschen
app.delete("/todos/:id", (c) => {
  const idx = todos.findIndex((t) => t.id === c.req.param("id"));
  if (idx === -1) return c.json({ error: "Not found" }, 404);
  todos.splice(idx, 1);
  return c.json({ message: "Deleted" });
});

serve({ fetch: app.fetch, port: 3000 }, () => {
  console.log("Server running at http://localhost:3000");
});

Testen Sie es aus:

# Todo erstellen
curl -X POST http://localhost:3000/todos \
  -H "Content-Type: application/json" \
  -d '{"title": "Claude Code ausprobieren"}'

# Alle Todos abrufen
curl http://localhost:3000/todos

# Löschen (ID von oben verwenden)
curl -X DELETE http://localhost:3000/todos/<id>

---

Step 2: Validierung hinzufügen

„Ein leerer Titel lässt sich immer noch erstellen” oder „Jede Zeichenkette funktioniert als ID” — Validierung verhindert diese Probleme. Fragen Sie Claude Code:

claude -p "
Füge Validierung mit zod für POST /todos und PUT /todos/:id hinzu.
- title: string, 1-100 Zeichen
- done: (nur PUT) boolean
Bei Validierungsfehler 400 mit spezifischer Fehlermeldung zurückgeben
"

npm install zod

Claude Code fügt zod-Schemas hinzu:

import { z } from "zod";

const CreateTodoSchema = z.object({
  title: z.string().min(1, "Titel muss mindestens 1 Zeichen haben").max(100, "Titel darf maximal 100 Zeichen haben"),
});

const UpdateTodoSchema = z.object({
  title: z.string().min(1).max(100).optional(),
  done: z.boolean().optional(),
});

// POST /todos (mit Validierung)
app.post("/todos", async (c) => {
  const body = await c.req.json().catch(() => ({}));
  const result = CreateTodoSchema.safeParse(body);
  if (!result.success) {
    return c.json({ error: result.error.flatten().fieldErrors }, 400);
  }
  const todo: Todo = {
    id: crypto.randomUUID(),
    title: result.data.title,
    done: false,
    createdAt: new Date().toISOString(),
  };
  todos.push(todo);
  return c.json(todo, 201);
});

Validierungsfehler prüfen:

# Erstellen ohne Titel → sollte Fehler erzeugen
curl -X POST http://localhost:3000/todos \
  -H "Content-Type: application/json" \
  -d '{}'
# → {"error":{"title":["Titel muss mindestens 1 Zeichen haben"]}}

---

Step 3: Fehlerbehandlung vereinheitlichen

Derzeit gibt jeder Endpunkt Fehler in verschiedenen Formaten zurück. Lassen Sie Claude Code das standardisieren:

claude -p "
Fehlerbehandlung vereinheitlichen.
- Gemeinsames Fehlerantwortformat: { error: { code: string, message: string } }
- 404: NOT_FOUND
- 400: VALIDATION_ERROR
- 500: INTERNAL_SERVER_ERROR
Globalen Fehlerhandler mit Honos onError implementieren
"

// Fehlertypendefinition
class AppError extends Error {
  constructor(
    public code: string,
    public message: string,
    public statusCode: number = 400
  ) {
    super(message);
  }
}

// Globaler Fehlerhandler
app.onError((err, c) => {
  if (err instanceof AppError) {
    return c.json(
      { error: { code: err.code, message: err.message } },
      err.statusCode as any
    );
  }
  console.error(err);
  return c.json(
    { error: { code: "INTERNAL_SERVER_ERROR", message: "Ein unerwarteter Fehler ist aufgetreten" } },
    500
  );
});

// Verwendung
app.get("/todos/:id", (c) => {
  const todo = todos.find((t) => t.id === c.req.param("id"));
  if (!todo) throw new AppError("NOT_FOUND", "Todo nicht gefunden", 404);
  return c.json(todo);
});

---

Step 4: Swagger UI Dokumentation automatisch generieren

Wenn Sie eine API gebaut haben, brauchen Sie auch Dokumentation. Claude Code richtet das in Minuten ein:

claude -p "
Verwende @hono/swagger-ui und @hono/zod-openapi um
Swagger UI unter /docs hinzuzufügen.
Füge OpenAPI-Schemas zu den bestehenden Endpunkten hinzu.
"

npm install @hono/swagger-ui @hono/zod-openapi

Danach können Sie unter http://localhost:3000/docs Ihre API-Dokumentation einsehen.

---

Der Claude Code API-Entwicklungsworkflow (Zusammenfassung)

So sieht mein täglicher Entwicklungsablauf aus:

1. Claude Code mitteilen: "Ich brauche eine API, die X macht"
    ↓
2. Generierten Code überprüfen und testen
    ↓
3. Iterieren: "Das korrigieren", "Validierung hinzufügen", etc.
    ↓
4. git commit wenn Tests bestehen

Mein erster Stolperstein (echte Erfahrung)

Bei meiner ersten API habe ich die Fehlerbehandlung komplett weggelassen und musste sie später nachträglich hinzufügen — was ewig dauerte. Jetzt füge ich einfach „inklusive Fehlerbehandlung” zu meinem Prompt hinzu, und der Code kommt von Anfang an sauber raus. Der Trick bei Claude Code ist, alle Anforderungen von Anfang an zu nennen.

---

3 häufige Fallstricke

Fallstrick 1: JSON-Parse-Fehler ignorieren

// ❌ Fehler hier bleiben unbemerkt
const body = await c.req.json();

// ✅ Parse-Fehler abfangen
const body = await c.req.json().catch(() => null);
if (!body) return c.json({ error: "Invalid JSON" }, 400);

Fallstrick 2: 404 und 400 verwechseln

400: Die Anfrage selbst ist falsch (Validierungsfehler, fehlendes Pflichtfeld)
404: Die Ressource existiert nicht (ID nicht gefunden)
422: Anfrageformat korrekt, aber kann nicht verarbeitet werden

Fragen Sie Claude Code „Sollte ich hier 404 oder 400 zurückgeben?” und Sie erhalten die richtige Antwort.

Fallstrick 3: Alles im Arbeitsspeicher speichern

Der Code in diesem Leitfaden verwendet ein In-Memory-Array für Demozwecke. Daten verschwinden beim Neustart des Servers. In der Produktion brauchen Sie eine Datenbank wie PostgreSQL oder MongoDB. Sagen Sie Claude Code einfach „Speichere das in SQLite statt im Arbeitsspeicher” und es kümmert sich um die Migration.

---

Nächste Schritte

Wenn Sie die REST-API-Grundlagen beherrschen, probieren Sie Folgendes aus:

Schritt	Was zu tun ist
Datenbank	SQLite → PostgreSQL (mit Prisma)
Authentifizierung	JWT-Token-Auth hinzufügen
Tests	API-Tests mit vitest schreiben
Deployment	Auf Vercel / Cloudflare Workers veröffentlichen

Für all das sagen Sie Claude Code einfach „X hinzufügen” und die Basis ist in Minuten fertig. Bauen Sie zuerst etwas, das funktioniert — das ist der schnellste Weg.

Verwandte Artikel

• Claude Code REST API Design, Implementierung & Tests in Rekordzeit
• Claude Code Vollständiger Einsteigerleitfaden
• Claude Code Sicherheits-Best-Practices