Claude Code + REST API: Von der Spec zum laufenden Endpoint

Wer als Backend-Entwickler täglich REST APIs baut, kennt das Muster: Spec schreiben, Routen anlegen, Validierung ergänzen, Auth-Middleware einhängen, Tests schreiben, Doku pflegen. Jeder dieser Schritte kostet Zeit — und keiner davon ist wirklich kreativ. Genau hier verändert Claude Code REST API-Entwicklung grundlegend.

Claude Code ist kein einfacher Code-Completion-Service. Es versteht den gesamten Kontext deines Projekts: bestehende Routen, Typen, Fehlerbehandlungs-Patterns, Abhängigkeiten. Dieser Artikel zeigt fünf konkrete Workflows für die REST API Entwicklung mit KI — und ein vollständiges Beispiel, das du sofort in dein Projekt übernehmen kannst.

Von der natürlichen Sprache zur laufenden API

Der klassische API-Entwicklungszyklus dauert je nach Komplexität Stunden bis Tage. Mit Claude Code API Entwicklung verkürzt sich dieser Zyklus drastisch — nicht weil der Code magisch entsteht, sondern weil die mechanischen Übersetzungsschritte entfallen.

Der typische Flow sieht so aus:

1. Intent beschreiben — "Ich brauche eine CRUD-API für Produkte, PostgreSQL, Express, TypeScript"
2. OpenAPI Spec generieren lassen — vollständig, mit allen Response-Schemas
3. Endpoints implementieren lassen — inklusive Validierung und Error Handling
4. Middleware ergänzen — Auth, Rate Limiting, Logging in einem Prompt
5. Tests schreiben lassen — Jest + Supertest, alle Edge Cases abgedeckt

5 konkrete Backend-Workflows mit Claude Code

• API Design: OpenAPI Spec aus natürlicher Sprache

  Beschreibe deine Ressourcen und Aktionen — Claude generiert eine vollständige OpenAPI 3.1 YAML-Spec mit Request/Response-Schemas, Query-Parametern und Status-Codes.

• Endpoint-Implementierung mit Validierung

  "Implementiere POST /api/users mit E-Mail-Validierung, Passwort-Hashing (bcrypt), Zod-Schema und strukturierten Error-Responses." — fertig in Sekunden, TypeScript-typsicher.

• Middleware-Generierung: Auth, Rate Limiting, Logging

  JWT-Middleware, express-rate-limit mit Redis-Backend, strukturiertes Request-Logging mit Correlation-IDs — als kohärentes Paket, nicht als Copy-Paste-Fragmente.

• Integration Tests mit Jest + Supertest

  Claude Code schreibt Tests die wirklich alle Pfade abdecken: Happy Path, Validation Errors, Auth Failures, Not Found, Rate Limit Hits. Inklusive Test-DB-Setup.

• API-Dokumentation mit Beispiel-Requests

  README mit curl-Beispielen, TypeScript-Client-Snippets, Environment-Setup und Deployment-Hinweisen — aus dem bestehenden Code generiert, immer aktuell.

Vollbeispiel: CRUD Endpoint für /api/products

Ein konkreter Prompt für einen vollständigen Produkt-CRUD:

Route Definition (Express + TypeScript)

// src/routes/products.ts
import { Router, Request, Response } from 'express';
import { z } from 'zod';
import { ProductService } from '../services/product.service';
import { requireAuth } from '../middleware/auth';
import { asyncHandler } from '../middleware/async-handler';

export const productRouter = Router();

// GET /api/products — public
productRouter.get('/', asyncHandler(async (req: Request, res: Response) => {
  const { category, page = 1, limit = 20 } = req.query;
  const products = await ProductService.list({
    category: category as string | undefined,
    page: Number(page),
    limit: Math.min(Number(limit), 100),
  });
  res.json({ data: products.items, meta: products.meta });
}));

// GET /api/products/:id — public
productRouter.get('/:id', asyncHandler(async (req, res) => {
  const product = await ProductService.findById(req.params.id);
  if (!product) {
    return res.status(404).json({
      code: 'NOT_FOUND',
      message: `Product ${req.params.id} not found`,
    });
  }
  res.json({ data: product });
}));

// POST /api/products — requires auth
productRouter.post('/', requireAuth, asyncHandler(async (req, res) => {
  const body = CreateProductSchema.parse(req.body); // throws ZodError on invalid
  const product = await ProductService.create(body);
  res.status(201).json({ data: product });
}));

// PUT /api/products/:id — requires auth
productRouter.put('/:id', requireAuth, asyncHandler(async (req, res) => {
  const body = UpdateProductSchema.parse(req.body);
  const product = await ProductService.update(req.params.id, body);
  if (!product) return res.status(404).json({ code: 'NOT_FOUND', message: 'Product not found' });
  res.json({ data: product });
}));

// DELETE /api/products/:id — requires auth
productRouter.delete('/:id', requireAuth, asyncHandler(async (req, res) => {
  await ProductService.delete(req.params.id);
  res.status(204).send();
}));

Input Validation mit Zod

// src/schemas/product.schema.ts
import { z } from 'zod';

const CategoryEnum = z.enum(['electronics', 'clothing', 'food']);

export const CreateProductSchema = z.object({
  name:     z.string().min(1).max(100),
  price:    z.number().positive('Price must be greater than 0'),
  category: CategoryEnum,
});

export const UpdateProductSchema = CreateProductSchema.partial();

// TypeScript types — abgeleitet aus dem Schema, immer in sync
export type CreateProductDTO = z.infer<typeof CreateProductSchema>;
export type UpdateProductDTO = z.infer<typeof UpdateProductSchema>;

export interface Product {
  id:        string;   // UUID v4
  name:      string;
  price:     number;
  category:  'electronics' | 'clothing' | 'food';
  createdAt: Date;
}

Globales Error Handling

// src/middleware/error-handler.ts
import { ZodError } from 'zod';
import { ErrorRequestHandler } from 'express';

export const globalErrorHandler: ErrorRequestHandler = (err, req, res, next) => {
  // Zod validation error → 400
  if (err instanceof ZodError) {
    return res.status(400).json({
      code:    'VALIDATION_ERROR',
      message: 'Invalid request body',
      details: err.issues.map(i => ({ field: i.path.join('.'), message: i.message })),
    });
  }

  // JWT / Auth errors → 401
  if (err.name === 'JsonWebTokenError' || err.name === 'TokenExpiredError') {
    return res.status(401).json({ code: 'UNAUTHORIZED', message: 'Invalid or expired token' });
  }

  // Known app errors (AppError class)
  if (err.isOperational) {
    return res.status(err.statusCode).json({ code: err.code, message: err.message });
  }

  // Unhandled → 500, log details server-side only
  console.error('[ERROR]', { requestId: req.headers['x-request-id'], error: err });
  res.status(500).json({ code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' });
};

Integration Test mit Jest + Supertest

// tests/api/products.test.ts
import request from 'supertest';
import { app } from '../../src/app';
import { generateTestToken } from '../helpers/auth';
import { db } from '../helpers/db';

let authToken: string;

beforeAll(async () => {
  await db.migrate(); // test DB setup
  authToken = await generateTestToken({ role: 'admin' });
});
afterEach(() => db.truncate('products'));
afterAll(() => db.close());

describe('POST /api/products', () => {
  it('201 — creates product with valid payload', async () => {
    const res = await request(app)
      .post('/api/products')
      .set('Authorization', `Bearer ${authToken}`)
      .send({ name: 'Laptop Pro', price: 1299.99, category: 'electronics' });

    expect(res.status).toBe(201);
    expect(res.body.data).toMatchObject({ name: 'Laptop Pro', category: 'electronics' });
    expect(res.body.data.id).toBeDefined();
  });

  it('400 — rejects negative price', async () => {
    const res = await request(app)
      .post('/api/products')
      .set('Authorization', `Bearer ${authToken}`)
      .send({ name: 'Test', price: -10, category: 'food' });

    expect(res.status).toBe(400);
    expect(res.body.code).toBe('VALIDATION_ERROR');
    expect(res.body.details[0].field).toBe('price');
  });

  it('401 — rejects missing token', async () => {
    const res = await request(app)
      .post('/api/products')
      .send({ name: 'Test', price: 10, category: 'food' });

    expect(res.status).toBe(401);
  });
});

describe('GET /api/products/:id', () => {
  it('404 — returns structured error for unknown id', async () => {
    const res = await request(app).get('/api/products/00000000-0000-0000-0000-000000000000');
    expect(res.status).toBe(404);
    expect(res.body.code).toBe('NOT_FOUND');
  });
});

Error-Handling Patterns die Claude Code kennt

Eines der häufigsten Probleme in selbst geschriebenen APIs ist inkonsistentes Error-Handling. Claude Code kennt alle Standard-HTTP-Fehlermuster und setzt sie konsistent um — wenn du es explizit anweist.

Wichtig: Bei 500-Fehlern loggt der Server den vollständigen Stack-Trace — die API-Response enthält aber nur eine generische Meldung ohne interne Details. Das verhindert Information Leakage.

API Security: Was Claude Code automatisch berücksichtigt

Wenn du Claude Code explizit auf Sicherheit hinweist ("implementiere mit Security Best Practices"), berücksichtigt es standardmäßig folgende Patterns:

Prompt-Template für komplette API-Entwicklung

Dieses Template hat sich in der Praxis für vollständige Backend-API-Entwicklung mit Claude Code bewährt. Kopiere es und ersetze die Platzhalter:

Warum dieses Template funktioniert

Der Prompt spezifiziert Constraints statt Implementierungsdetails. Claude Code entscheidet dann selbst, welches Zod-Refinement für den Email-Check am sinnvollsten ist — du gibst die Grenzen vor, nicht den Weg. Das Ergebnis ist konsistenter Code, weil Claude Code alle Entscheidungen im gleichen Kontext trifft, nicht schrittweise in isolierten Prompts.