Claude Code API Design: REST-APIs entwerfen und dokumentieren mit KI

Eine API ist kein Anhang zu einem Projekt — sie ist die Schnittstelle, an der andere Systeme und Entwickler scheitern oder erfolgreich sind. Schlechte Endpoints, inkonsistente Namenskonventionen, fehlende Fehlercodes, eine Dokumentation die nicht mit dem Code mitwächst: das sind nicht akademische Probleme, sondern die Hauptgründe warum Integrationen Wochen statt Tage dauern.

Claude Code verändert den API-Design-Prozess grundlegend — nicht weil es einen Algorithmus für gutes API-Design hat, sondern weil es den gesamten Kontext deines Projekts gleichzeitig sieht. Es kennt deine bestehenden Datenmodelle, deine Namenskonventionen, deine Fehlerbehandlung — und entwirft neue Endpoints konsequent dazu passend. Dieser Artikel zeigt, wie das konkret funktioniert: von den ersten Endpoints bis zur vollständigen OpenAPI-Spec mit Tests.

1. REST-API-Grundlagen: Endpoints, HTTP-Methoden, Statuscodes

Bevor man Claude Code ins API-Design einbezieht, lohnt es sich, die Grundstruktur zu verstehen, die ein gutes REST-Design ausmacht. Nicht weil Claude Code sie nicht kennt — es kennt sie sehr gut — sondern weil man nur dann prüfen kann, ob ein Vorschlag wirklich passt.

Ressourcenorientierung ist das Fundament von REST. Endpoints beschreiben Ressourcen, keine Aktionen. /users ist eine Ressource, /getUsers ist eine Aktion — und der Unterschied ist nicht kosmetisch. Ressourcen-orientierte APIs sind vorhersehbar: ein Entwickler, der GET /users sieht, erwartet GET /users/{id}, POST /users, PUT /users/{id}, DELETE /users/{id} — ohne die Dokumentation zu lesen.

Claude Code lässt sich diese Konsistenz explizit durchsetzen:

claude "Analysiere meine bestehenden API-Routes in src/routes/ und
zeige mir, welche gegen REST-Konventionen verstossen. Erstelle dann
eine Liste aller fehlenden CRUD-Endpoints fuer jede Ressource."

Das Ergebnis ist eine Lückenanalyse: welche Endpoints existieren, welche fehlen, welche inkonsistent benannt sind. Das ist der Ausgangspunkt für jede API-Erweiterung.

HTTP-Methoden korrekt einsetzen

Die sieben wichtigsten HTTP-Methoden haben klar definierte Semantiken:

• GET — Daten lesen, keine Seiteneffekte, cacheable
• POST — neue Ressource erstellen oder komplexe Aktion auslösen
• PUT — Ressource vollständig ersetzen (idempotent)
• PATCH — Ressource partiell aktualisieren
• DELETE — Ressource löschen (idempotent)
• HEAD — wie GET, aber nur Header, kein Body
• OPTIONS — verfügbare Methoden abfragen (CORS preflight)

Ein häufiger Fehler: PATCH und PUT zu vermischen. Claude Code erkennt das:

claude "In meiner UserController-Klasse wird PUT /users/{id} verwendet,
um einzelne Felder zu aktualisieren. Ist das korrekt? Was sollte ich
ändern und warum?"

HTTP-Statuscodes konsequent nutzen

Eine API, die bei jedem Fehler 200 OK mit einem {"error": "..."} im Body zurückgibt, macht das Leben aller Aufrufer schwerer. Die richtigen Statuscodes sind nicht optional — sie sind der Vertrag zwischen deiner API und ihren Konsumenten.

Die wichtigsten Ranges:

• 2xx Erfolg: 200 OK, 201 Created, 204 No Content
• 3xx Weiterleitungen: 301 Moved Permanently, 304 Not Modified
• 4xx Client-Fehler: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests
• 5xx Server-Fehler: 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable

claude "Prüfe meine Error-Handler in src/middleware/errorHandler.ts
und zeige, wo ich die falschen HTTP-Statuscodes verwende. Erstelle
eine Tabelle: aktueller Code → korrekter Code → Begründung."

2. OpenAPI/Swagger-Spezifikation schreiben

OpenAPI (ehemals Swagger) ist der De-facto-Standard für die Beschreibung von REST-APIs. Eine vollständige OpenAPI-Spec ist mehr als Dokumentation — sie ist die Grundlage für automatisch generierte Client-SDKs, Mock-Server, Test-Suites und interaktive API-Browser.

Das Problem: eine OpenAPI-Spec für eine bestehende API von Hand zu schreiben ist mühsam. Für jede Route muss man Paths, Parameter, Request Bodies, Responses und Schema-Definitionen dokumentieren. Claude Code nimmt diese Arbeit ab:

claude "Lies alle Route-Definitionen in src/routes/ und generiere
eine vollständige OpenAPI 3.1 Spezifikation als openapi.yaml.
Inkludiere alle Parameter, Request Bodies, Response-Schemas und
möglichen Fehlercodes."

Claude Code liest die Routes, findet die dazugehörigen Controller, analysiert die Datenmodelle und generiert eine vollständige Spec — inklusive korrekter Schema-Definitionen für alle Objekte.

OpenAPI-Struktur verstehen

Eine minimale OpenAPI-Spec hat diese Struktur:

openapi: 3.1.0
info:
  title: Meine API
  version: 1.0.0
  description: Kurze Beschreibung

paths:
  /users:
    get:
      summary: Liste aller Benutzer
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Erfolgreich
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        createdAt:
          type: string
          format: date-time

Claude Code generiert nicht nur diese Struktur — es befüllt sie mit den tatsächlichen Datenmodellen aus deinem Code. Wenn dein User-Typ in TypeScript 12 Felder hat, stehen alle 12 in der Spec.

Spec aus bestehendem Code generieren und pflegen

Noch wertvoller als die Erstgenerierung ist die Pflege: wenn sich der Code ändert, ändert sich die Spec automatisch mit:

claude "Vergleiche openapi.yaml mit dem aktuellen Code in src/routes/.
Welche Endpoints fehlen in der Spec? Welche sind in der Spec aber
nicht mehr im Code? Aktualisiere die Spec entsprechend."

3. Versionierung und Backwards Compatibility

API-Versionierung ist das Thema, das erst wichtig wird, wenn es zu spät ist. Sobald eine API produktiv in Verwendung ist, sind breaking changes ein Problem — nicht für dich, sondern für alle Systeme, die sie nutzen. Eine gute Versionierungsstrategie verhindert, dass du zwischen "weiterentwickeln" und "nichts kaputt machen" wählen musst.

Die drei gängigen Ansätze:

• URL-Versionierung: /api/v1/users und /api/v2/users parallel
• Header-Versionierung: Accept: application/vnd.myapi.v2+json
• Query-Parameter: /api/users?version=2

URL-Versionierung ist am einfachsten zu debuggen und zu dokumentieren. Claude Code hilft bei der Strukturentscheidung:

claude "Meine API ist aktuell unversioniert. Ich plane breaking changes
in den nächsten drei Monaten. Welche Versionierungsstrategie empfiehlst
du für ein Node.js/Express-Backend mit ~20 Endpoints? Zeige mir die
Ordnerstruktur und einen Beispiel-Router."

Was ist ein Breaking Change?

Das ist die Frage, die viele falsch einschätzen. Nicht jede Änderung ist breaking:

• Non-breaking: Neues optionales Feld im Response-Body hinzufügen
• Non-breaking: Neuen optionalen Query-Parameter hinzufügen
• Non-breaking: Neuen Endpoint hinzufügen
• Breaking: Feld aus Response-Body entfernen
• Breaking: Pflichtfeld zum Request-Body hinzufügen
• Breaking: Datentyp eines bestehenden Felds ändern
• Breaking: URL-Struktur ändern
• Breaking: HTTP-Methode ändern

claude "Ich plane folgende Änderungen an meiner API: [Liste der
geplanten Änderungen]. Welche davon sind breaking changes? Für die
breaking changes: zeige mir, wie ich sie rückwärtskompatibel
implementieren kann, bevor ich die neue Version einführe."

Deprecation-Strategie

Alte API-Versionen können nicht ewig laufen. Eine klare Deprecation-Strategie kommuniziert, wann eine Version abgekündigt wird — per Response-Header, per Dokumentation, per E-Mail an registrierte Entwickler.

claude "Implementiere einen Deprecation-Warning-Middleware für Express,
der bei Requests auf /api/v1/* einen Sunset-Header setzt und in der
Response einen deprecation_warning-Field im JSON-Body ergänzt.
Sunset-Datum soll konfigurierbar sein."

Claude Code generiert nicht nur den Middleware-Code, sondern ergänzt ihn mit den korrekten RFC-konformen Header-Formaten (RFC 8594 für Sunset, RFC 8288 für Link: rel=deprecation).

4. Rate Limiting und Authentifizierung

Eine API ohne Rate Limiting und ohne solide Authentifizierung ist keine produktionsreife API. Das klingt selbstverständlich — aber in der Praxis werden beide Themen oft auf "später" verschoben, bis es zu spät ist. Claude Code hilft, sie von Anfang an sauber einzubauen.

JWT-Authentifizierung korrekt implementieren

JWT (JSON Web Tokens) ist der Standard für zustandslose API-Authentifizierung. Die typischen Implementierungsfehler sind: Tokens ohne Ablaufzeit, zu schwache Signing-Secrets, fehlende Token-Invalidierung, falsche Algorithmus-Auswahl.

claude "Implementiere JWT-Authentifizierung für meine Express-API.
Anforderungen:
- Access Token: 15 Minuten Gültigkeit
- Refresh Token: 7 Tage Gültigkeit, in httpOnly-Cookie
- Token-Rotation bei Refresh
- Blacklisting von invalidierten Tokens in Redis
- RS256-Algorithmus (asymmetrisch, kein HS256)
Zeige Middleware, Routes und Key-Generierung."

Claude Code generiert eine vollständige Implementierung — inklusive der häufig vergessenen Token-Rotation (nach jedem Refresh wird der alte Refresh-Token invalidiert) und der sicheren Cookie-Konfiguration.

API-Keys als Alternative

Für Server-zu-Server-Kommunikation sind API-Keys oft einfacher als JWT. Die Herausforderung ist das sichere Management:

claude "Implementiere ein API-Key-System für meine REST-API:
- Scoped Keys (read-only, read-write, admin)
- Key-Hashing in der Datenbank (nie Plaintext speichern)
- Rate-Limiting pro Key
- Key-Rotation ohne Downtime
- Audit-Log für alle Key-Nutzungen
Stack: Node.js, PostgreSQL, Redis."

Rate Limiting korrekt konfigurieren

Rate Limiting hat mehr Dimensionen als "X Requests pro Minute". Welches Fenster? Pro IP oder pro User? Pro Endpoint oder global? Was passiert bei Überschreitung?

claude "Implementiere Rate Limiting für meine Express-API mit Redis.
Konfiguration:
- Globales Limit: 1000 Requests/15min pro IP
- Auth-Endpoints: 10 Versuche/15min (strenger, Brute-Force-Schutz)
- API-Key-Endpoints: 10.000 Requests/Stunde pro Key
- Response-Header: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
- Bei Überschreitung: 429 mit Retry-After-Header
Nutze sliding window algorithm."

OAuth 2.0 für Public APIs

Wenn deine API von Drittanbieter-Applikationen genutzt werden soll, ist OAuth 2.0 der Standard. Die Implementierung ist komplex — Claude Code hilft beim richtigen Flow-Auswahl:

claude "Ich brauche OAuth 2.0 für meine API. Es gibt drei Use Cases:
1. Mobile Apps meiner eigenen Nutzer
2. Drittanbieter-Webapps die im Namen der Nutzer agieren
3. Server-zu-Server ohne Nutzer-Interaktion
Welcher OAuth-Flow passt jeweils? Zeige die Implementierung für den
wichtigsten Fall (Use Case 2) mit Node.js."

5. API-Dokumentation automatisch generieren

API-Dokumentation die von Hand geschrieben und gepflegt werden muss, wird zwangsläufig veralten. Sobald ein Endpoint geändert wird und die Dokumentation nicht mitgezogen wird, verliert sie ihren Wert. Die Lösung: Dokumentation die direkt aus dem Code oder der Spec generiert wird.

Swagger UI aus OpenAPI-Spec

Die einfachste Form interaktiver Dokumentation: Swagger UI, das direkt aus deiner openapi.yaml gerendert wird. Integration in Express in wenigen Zeilen:

claude "Integriere Swagger UI in meine Express-App. Die openapi.yaml
liegt im Root-Verzeichnis. Die Dokumentation soll unter /api-docs
erreichbar sein, aber nur in non-production Environments. Für
Production soll sie per API-Key geschützt sein."

Claude Code generiert die Integration, inklusive des Environment-Checks und des optionalen Basic-Auth-Schutzes für den Produktiv-Einsatz.

JSDoc/TSDoc zu OpenAPI

Für Teams die Code-first arbeiten (Spec wird aus Code generiert, nicht umgekehrt): JSDoc-Kommentare im Code können direkt in OpenAPI umgewandelt werden.

claude "Füge JSDoc-Kommentare zu allen Route-Handlers in src/routes/
hinzu, die als Grundlage für swagger-jsdoc genutzt werden können.
Jede Route soll Folgendes dokumentieren:
- @openapi-Tag mit vollständigem Path-Object
- Alle Parameter und ihre Typen
- Request-Body-Schema
- Alle möglichen Response-Codes mit Beispielen"

Automatische Changelog-Generierung

Eine oft übersehene Form der Dokumentation: API-Changelogs. Welche Endpoints wurden geändert? Welche neuen Parameter gibt es? Welche alten Verhaltensweisen sind jetzt anders?

claude "Vergleiche openapi.yaml im aktuellen Branch mit openapi.yaml
im main-Branch. Generiere einen API-Changelog im Format:

## Breaking Changes
- ...

## Neue Endpoints
- ...

## Änderungen an bestehenden Endpoints
- ..."

Dokumentation in mehreren Sprachen

Für internationale Produkte: Claude Code kann API-Dokumentation übersetzen und dabei technische Begriffe korrekt behandeln:

claude "Die Dokumentation in openapi.yaml ist auf Englisch. Erstelle
eine openapi.de.yaml mit deutschen Beschreibungen. Technische Begriffe
(HTTP-Methoden, Statuscodes, JSON-Felder) bleiben auf Englisch."

6. Testing und Mocking von APIs

Eine gut entworfene API ist nichts wert, wenn sie nicht getestet ist. API-Testing hat mehrere Schichten: Unit-Tests für einzelne Handler, Integrationstests für vollständige Request-Response-Zyklen, Contract-Tests um sicherzustellen dass die Implementierung der Spec entspricht, und Lasttests für Rate-Limiting und Performance.

Integrationstests mit Supertest

Für Express-APIs ist Supertest die Standardlösung für Integrationstests — es startet die App in einem Test-Server und sendet echte HTTP-Requests:

claude "Schreibe Integrationstests mit Jest und Supertest für alle
Endpoints in src/routes/users.ts. Jeder Test soll:
- Erfolgreiche Requests prüfen (inkl. Response-Body-Schema)
- Fehlerszenarien prüfen (fehlende Auth, ungültige Daten, nicht gefunden)
- HTTP-Statuscodes explizit prüfen
- Test-Datenbank nutzen (nicht die Produktiv-DB)
Nutze beforeAll/afterAll für DB-Setup und Teardown."

Claude Code liest die Route-Definitionen und Controller, versteht die Datenmodelle und generiert Tests die alle relevanten Szenarien abdecken — inklusive Edge Cases wie leere Listen, sehr lange Strings, ungültige UUIDs.

Contract-Tests: Spec gegen Implementierung prüfen

Contract-Tests prüfen, ob die Implementierung tatsächlich dem entspricht, was in der OpenAPI-Spec dokumentiert ist. Das ist die höchste Form der Konsistenzprüfung:

claude "Richte Dredd (oder openapi-backend mit Jest) ein, um bei
jedem Test-Run zu prüfen ob alle Endpoints in openapi.yaml korrekt
implementiert sind. Füge das als npm-Script 'test:contract' hinzu
und integriere es in den CI-Workflow."

Mock-Server für Frontend-Entwicklung

Ein Mock-Server, der auf Basis der OpenAPI-Spec antwortet, ermöglicht Frontend-Entwicklung unabhängig vom Backend-Team:

claude "Richte einen Mock-Server mit Prism (stoplight/prism) auf Basis
von openapi.yaml ein. Der Server soll:
- Auf Port 4010 laufen
- Validierungsfehler zurückgeben wenn Requests nicht der Spec entsprechen
- Realistische Beispieldaten generieren
- Als Docker-Container startbar sein
Erstelle docker-compose.mock.yml und package.json-Script 'mock:server'."

Claude Code generiert nicht nur die Konfiguration, sondern ergänzt die openapi.yaml um Beispieldaten in den Schema-Definitionen — so dass der Mock-Server realistische Antworten liefert statt generischer Platzhalter.

Lasttest und Rate-Limiting testen

claude "Schreibe einen Lasttest mit k6, der das Rate-Limiting meiner
API testet:
1. Sende 100 Requests/Sekunde von einer IP
2. Prüfe dass nach dem konfigurierten Limit 429 zurückkommt
3. Prüfe dass Retry-After-Header korrekt gesetzt ist
4. Prüfe dass nach der Wartezeit wieder 200 kommt
Ausgabe: Bericht mit Percentile-Latenzwerten und Fehlerrate."

API-Design-Prüfliste mit Claude Code

Zum Abschluss einer API-Design-Phase ist eine vollständige Review sinnvoll:

claude "Prüfe meine API auf folgende Punkte und erstelle einen
Bericht mit Bewertung (OK / Verbesserungsbedarf / Kritisch):

1. Konsistente Namenskonventionen (snake_case vs camelCase?)
2. Alle Endpoints ressourcenorientiert?
3. HTTP-Methoden korrekt verwendet?
4. Alle relevanten Statuscodes implementiert?
5. Fehlermeldungen aussagekräftig und konsistent?
6. Paginierung bei Listen-Endpoints?
7. Rate-Limiting vorhanden?
8. Authentifizierung vollständig implementiert?
9. OpenAPI-Spec vollständig und aktuell?
10. Tests vorhanden und aussagekräftig?"

Dieses Audit läuft in Minuten und deckt Probleme auf, für die ein manuelles Review Stunden bräuchte. Das Ergebnis ist keine Liste von Vermutungen, sondern konkrete Befunde mit Fundstellen im Code.

Zwei verwandte Artikel, die auf diesem Thema aufbauen:

• Claude Code mit FastAPI — REST-APIs in Python mit automatischer OpenAPI-Generierung
• Claude Code und GraphQL — wenn REST nicht mehr ausreicht: Schema-Design und Resolver