REST API Design mit Claude Code: Best Practices 2026

# Prompt: "Review diese API-Endpoints und korrigiere alles was nicht RESTful ist" # ❌ SCHLECHT — Claude Code identifiziert und erklärt: GET /getUsers # Verb im URL — NICHT RESTful POST /createUser # Verb im URL GET /user_list # Underscore + Singular statt Plural POST /user/delete/123 # DELETE-Aktion als POST # ✅ GUT — Claude Code generiert korrekte Version: GET /users # Liste aller User POST /users # Neuen User erstellen GET /users/{id} # Einzelnen User laden PUT /users/{id} # User komplett ersetzen PATCH /users/{id} # User teilweise aktualisieren DELETE /users/{id} # User löschen # Verschachtelte Ressourcen: GET /users/{id}/orders # Orders eines Users POST /users/{id}/orders # Order für User erstellen GET /users/{id}/orders/{oid} # Spezifische Order # Query Parameter für Filter/Sort/Search: GET /products?category=electronics&sort=price&order=asc&q=laptop

# Konsistentes Error-Response Format (RFC 7807): { "type": "https://api.example.com/errors/validation", "title": "Validation Failed", "status": 400, "detail": "The request body contains invalid fields", "errors": [ { "field": "email", "message": "Must be a valid email address" }, { "field": "age", "message": "Must be at least 18" } ] }

# Cursor-based Pagination (besser als offset bei großen Datenmengen): GET /users?limit=20&cursor=eyJpZCI6MTAwfQ== # Response: { "data": [...], "pagination": { "nextCursor": "eyJpZCI6MTIwfQ==", "hasMore": true, "total": 1500 } } # API Versionierung — 3 Ansätze: # 1. URL Path (am verbreitetsten): GET /api/v1/users GET /api/v2/users # 2. Accept Header: Accept: application/vnd.example.v2+json # 3. Custom Header: API-Version: 2 # Claude Code empfiehlt: URL Path für Einfachheit, # Accept Header für strikte REST-Konformität

# Prompt: "Generiere OpenAPI-Spec für diesen Express-Router" # openapi.yml — Claude Code erstellt vollständige Spec: openapi: '3.1.0' info: title: Users API version: '2.0' paths: /users: get: summary: List users parameters: - name: limit in: query schema: { type: integer, default: 20, maximum: 100 } responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserList' # In Express mit zod-openapi automatisch generieren: import { OpenApiGeneratorV31 } from '@asteasolutions/zod-to-openapi' # → Keine manuelle YAML mehr — aus Zod-Schemas generiert!