Skip to content

AI für REST API Design & Dokumentation

8. März 2026 Künstliche Intelligenz By MetinC

AI für REST API Design & Dokumentation: Endpoints, OpenAPI, Versionierung und Best Practices mit ChatGPT & Claude. 10 Prompts für professionelle APIs.

Einleitung

Gute APIs sind das Rückgrat jeder modernen Software. Zusätzlich kI hilft beim Design, der Dokumentation und dem Testen von REST APIs nach Best Practices. Hier sind 10 Prompts für professionelles API-Design.

Im Folgenden gehe ich auf die wichtigsten Details ein.

Inhaltsverzeichnis

  1. Prompt 1: API-Endpunkte designen
  2. Prompt 2: OpenAPI Spezifikation erstellen
  3. Prompt 3: Resource Naming Conventions
  4. Prompt 4: Error Response Standard
  5. Prompt 5: Pagination & Filtering
  6. Prompt 6: API Versionierung
  7. Prompt 7: Authentication & Authorization
  8. Prompt 8: Rate Limiting & Throttling
  9. Prompt 9: API Dokumentation schreiben
  10. Prompt 10: API Testing Strategie
  11. FAQ

Zudem lassen sich die Ergebnisse auch auf andere Projekte übertragen.

Prompt 1: API-Endpunkte designen

Insbesondere für den Einstieg sind die folgenden Informationen hilfreich.

Designe REST API Endpunkte für:

Projekt: [z.B. "Task Management App" / "E-Commerce" / "Social Media"]
Entitäten: [z.B. "Users, Tasks, Projects, Comments"]

Erstelle für jede Entität:
1. CRUD Endpunkte (GET, POST, PUT/PATCH, DELETE)
2. Nested Resources (z.B. /projects/:id/tasks)
3. HTTP Methods korrekt zuordnen
4. Status Codes für jeden Response (200, 201, 204, 400, 404, 409)
5. Request Body Format (JSON)
6. Response Format (konsistente Struktur)
7. Query Parameter für Filtering (?status=active)
8. Relationship Endpunkte (z.B. /users/:id/tasks)

Format als Tabelle:
| Method | Endpoint | Description | Request | Response | Status |

Weiterhin ist es ratsam, die Ergebnisse immer kritisch zu prüfen.

Weiterhin ist es sinnvoll, die Ergebnisse regelmäßig zu überprüfen.

Prompt 2: OpenAPI Spezifikation erstellen

Ebenso wichtig ist es, die Best Practices zu kennen.

Erstelle eine OpenAPI 3.1 Spezifikation:

API: [z.B. "User Management API"]
Endpunkte: [Liste der Endpunkte]

YAML mit:
1. info (title, version, description, contact)
2. servers (development, staging, production)
3. paths (alle Endpunkte mit Operationen)
4. components/schemas (alle Entitäten als JSON Schema)
5. components/responses (Standard-Responses: 400, 401, 404, 500)
6. components/parameters (wiederverwendbare Parameter)
7. components/securitySchemes (Bearer Token, API Key)
8. tags (Gruppierung der Endpunkte)
9. examples (Request/Response Beispiele)
10. Webhooks (falls Events nach außen gehen)

Generiere daraus:
- Swagger UI Konfiguration
- TypeScript Types (mit openapi-typescript)
- Postman Collection Export

Somit sparst du Zeit und erhältst qualitativ hochwertigeren Output.

Folglich verbessert sich die gesamte Codequalität deutlich.

Prompt 3: Resource Naming Conventions

Dennoch solltest du einige Besonderheiten beachten.

Erstelle Naming Conventions für meine REST API:

Entitäten: [z.B. "Users, BlogPosts, OrderItems, ProductCategories"]

Regeln definieren für:
1. Plural vs. Singular (/users vs. /user)
2. kebab-case vs. camelCase (in URLs)
3. Nested Resources (max. Tiefe?)
4. Query Parameter Benennung (snake_case: sort_by, page_size)
5. JSON Property Naming (camelCase im Body)
6. ID Format (UUID vs. numeric vs. nanoid)
7. Action Endpoints (/users/:id/activate – POST, nicht GET!)
8. Bulk Operations (/users/bulk-delete)
9. Search Endpoint (/search?q=term)
10. Versionierung im Pfad (/v1/users) vs. Header

Erstelle ein API Style Guide Dokument.

Außerdem kannst du den Prompt für verschiedene Programmiersprachen anpassen.

Dabei ist der folgende Punkt besonders wichtig.

Prompt 4: Error Response Standard

Deshalb lohnt es sich, dieses Thema genauer zu betrachten.

Erstelle einen Standard für API Error Responses:

Implementiere RFC 7807 (Problem Details):
{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request body contains invalid fields",
  "instance": "/users/123",
  "errors": [
    { "field": "email", "message": "Invalid email format" }
  ]
}

Definiere:
1. Fehler-Hierarchie (Business vs. Technical vs. Validation)
2. Error Codes System (ERR_USER_NOT_FOUND, ERR_RATE_LIMIT)
3. Status Code Mapping (welcher HTTP Code für welchen Fehler?)
4. Validation Errors (Feld-spezifische Fehler-Liste)
5. Localization (Fehlermeldungen in DE/EN)
6. Error Logging (was loggen, was nicht? PII!)
7. Stack Traces (nur Development, nie Production)
8. Retry-After Header (für 429, 503)
9. Error Documentation (für API-Nutzer)
10. Client-Side Error Handling Empfehlung

Darüber hinaus solltest du diesen Aspekt berücksichtigen.

Prompt 5: Pagination & Filtering

Ebenfalls relevant sind die praktischen Anwendungsbeispiele.

Implementiere Pagination und Filtering für meine API:

Endpunkt: GET /api/v1/[resource]
Datenmenge: [z.B. "100.000+ Einträge"]

Implementiere:
1. **Offset Pagination**: ?page=2&page_size=20
2. **Cursor Pagination**: ?cursor=abc123&limit=20
3. **Wann welche?** (Offset für UI, Cursor für Feeds/APIs)
4. **Response Format**: { data: [], meta: { total, page, pages } }
5. **Filtering**: ?status=active&role=admin
6. **Sorting**: ?sort=created_at&order=desc
7. **Field Selection**: ?fields=id,name,email
8. **Full-Text Search**: ?q=suchbegriff
9. **Range Filter**: ?created_after=2024-01-01&price_min=10
10. **Link Headers**: RFC 8288 (next, prev, first, last)

Performance:
- DB Index Strategie für häufige Filter
- Maximum page_size Limit (z.B. 100)
- Caching für identische Queries

Dementsprechend ist eine manuelle Überprüfung empfehlenswert.

Natürlich kannst du den Ansatz an deine Bedürfnisse anpassen.

Prompt 6: API Versionierung

Im Grunde vereinfacht dieser Ansatz den gesamten Workflow erheblich.

Erstelle eine Versionierungsstrategie für meine API:

Aktuelle Version: v1
Geplante Breaking Changes: [z.B. "User-Schema ändert sich, neues Auth-System"]

Vergleiche Ansätze:
1. **URL Versioning**: /api/v1/users vs. /api/v2/users
2. **Header Versioning**: Accept: application/vnd.api+json;version=2
3. **Query Parameter**: /api/users?version=2

Implementiere:
4. Deprecation Strategie (Sunset Header, Deprecation Header)
5. Migrations-Pfad für Clients (v1 → v2)
6. Breaking vs. Non-Breaking Changes definieren
7. Changelog Format (für API-Nutzer)
8. Parallel Betrieb (v1 + v2 gleichzeitig)
9. Sunset Policy (wie lange bleibt v1 aktiv?)
10. Feature Flags statt neue Version (wann sinnvoll?)

Empfehlung: Welcher Ansatz für mein Projekt?

Tatsächlich lässt sich dieser Code direkt in dein Projekt übernehmen.

Dementsprechend solltest du die einzelnen Schritte sorgfältig abarbeiten.

Prompt 7: Authentication & Authorization

Weiterhin ist es wichtig, die Grundlagen zu verstehen.

Implementiere Auth für meine REST API:

Typ: [Public API / Internal / B2B / Mobile App]
User Roles: [z.B. "Admin, Editor, Viewer"]

Implementiere:
1. **JWT Authentication**: Access Token + Refresh Token Flow
2. **API Key**: Für Service-to-Service Kommunikation
3. **OAuth 2.0**: Authorization Code Flow (für Third-Party)
4. **RBAC**: Role-Based Access Control Middleware
5. **Resource-Level Auth**: User darf nur eigene Daten ändern
6. **Rate Limiting**: Per API Key / Per User / Per IP
7. **CORS**: Allowed Origins konfigurieren
8. **Token Rotation**: Refresh Token Rotation Strategy
9. **Scopes**: Granulare Berechtigungen (read:users, write:users)
10. **Audit Log**: Wer hat wann was geändert?

Security Checklist:
- Token Expiry (Access: 15min, Refresh: 7 Tage)
- HTTPS Only, Secure Cookies
- No sensitive data in JWT Payload

Ebenfalls sinnvoll ist es, verschiedene Varianten auszuprobieren.

Außerdem profitierst du von einem systematischen Vorgehen.

Prompt 8: Rate Limiting & Throttling

Dementsprechend solltest du die folgenden Aspekte kennen.

Implementiere Rate Limiting für meine API:

Traffic: [z.B. "1000 Requests/Minute erwartet"]
Infrastruktur: [z.B. "Node.js, Redis, Nginx"]

Implementiere:
1. **Fixed Window**: 100 Requests pro Minute
2. **Sliding Window**: Gleichmäßigere Verteilung
3. **Token Bucket**: Burst-Tolerant
4. **Per-User Limits**: Unterschiedlich nach Plan (Free/Pro/Enterprise)
5. **Per-Endpoint Limits**: Schreib-Operationen strenger
6. **Redis-basierte Implementierung**: Für verteilte Systeme
7. **Response Headers**: X-RateLimit-Limit, -Remaining, -Reset
8. **429 Response**: Retry-After Header, hilfreiche Error Message
9. **Graceful Degradation**: Queue statt sofort ablehnen
10. **DDoS Protection**: Layer 7 Schutz (Cloudflare, Nginx)

Code für Node.js Middleware + Nginx Config.

Allerdings gibt es dabei einige Punkte, die du beachten solltest.

Prompt 9: API Dokumentation schreiben

Grundsätzlich gibt es dabei einige Punkte zu beachten.

Schreibe Dokumentation für meine API:

API: [Beschreibung oder OpenAPI Spec einfügen]
Zielgruppe: [Interne Entwickler / Externe Partner / Öffentlich]

Erstelle:
1. **Getting Started Guide**: Erster API Call in 5 Minuten
2. **Authentication Guide**: Wie Token erhalten und nutzen
3. **Endpoint Reference**: Für jeden Endpunkt komplett dokumentiert
4. **Code Examples**: cURL, JavaScript (fetch), Python (requests)
5. **Error Guide**: Alle Fehler-Codes mit Lösungen
6. **Rate Limit Info**: Limits erklären, Best Practices
7. **Changelog**: Was hat sich geändert?
8. **SDKs**: Auto-generierte Client Libraries (TypeScript, Python)
9. **Postman Collection**: Import-fertig
10. **FAQ**: Häufige Integrationsprobleme

Format: Markdown für Docusaurus / Mintlify / ReadMe.io

Grundsätzlich kannst du diesen Prompt an deine Bedürfnisse anpassen.

Zusammenfassend bietet dieser Abschnitt praktische Handlungsempfehlungen.

Prompt 10: API Testing Strategie

Dabei spielen mehrere Faktoren eine wichtige Rolle.

Erstelle eine API Testing Strategie:

API: [z.B. "REST API mit 30 Endpunkten, JWT Auth"]
Stack: [z.B. "Node.js, Jest, Supertest"]

Implementiere:
1. **Unit Tests**: Service Layer isoliert testen
2. **Integration Tests**: Endpunkt → DB → Response
3. **Contract Tests**: Pact oder OpenAPI Validation
4. **Load Tests**: k6 Script für Performance Testing
5. **Security Tests**: OWASP API Top 10 Checks
6. **E2E Flow Tests**: User registrieren → Login → CRUD → Delete
7. **Edge Cases**: Leere Bodies, ungültige IDs, Sonderzeichen
8. **Auth Tests**: Ohne Token, abgelaufen, falsche Rolle
9. **Pagination Tests**: Erste/letzte Seite, leere Results
10. **Test Data Factory**: Faker-basierte Test-Daten

CI/CD: GitHub Actions Pipeline mit Test + Coverage Report.

Insbesondere die Struktur des Prompts ist dabei entscheidend für gute Ergebnisse.

Somit ergibt sich ein klarer Vorteil gegenüber manuellen Methoden.

FAQ

REST oder GraphQL?

Außerdem gibt es hilfreiche Tools, die dich dabei unterstützen.

REST für die meisten APIs: einfacher, cacheable, standardisiert. GraphQL wenn der Client flexible Queries braucht (z.B. Mobile Apps, Dashboards). Neue Option: tRPC für Full-Stack TypeScript – End-to-End Type Safety ohne Schema.

Brauche ich eine OpenAPI Spec?

Vor allem für den praktischen Einsatz sind diese Informationen wertvoll.

Ja. Auch für interne APIs. OpenAPI ist die Basis für: automatische Dokumentation, Client-Generierung, Contract Testing und API Mocking. Schreibe die Spec zuerst (API-First Design) – AI hilft dabei.

Kann AI eine vollständige API designen?

Tatsächlich ist dieser Bereich besonders wichtig für Entwickler.

AI kann exzellente API-Entwürfe erstellen wenn du die Domäne beschreibst. Dabei am besten: Entitäten + Beziehungen + Use Cases definieren, AI erstellt Endpunkte, Schemas und OpenAPI Spec. Danach manuell Business Logic hinzufügen.

Ebenfalls empfehlenswert ist eine regelmäßige Überprüfung der Ergebnisse.

Verwandte Artikel:

Grundsätzlich empfiehlt es sich, schrittweise vorzugehen.

Zuletzt aktualisiert: März 2026