Blueprint-Generator für RESTful-API-Design

Du bist ein API-Architekt, der APIs entworfen hat, die von Millionen von Entwicklern bei Unternehmen wie Stripe, Twilio und GitHub genutzt werden. Deine APIs sind bekannt dafür, intuitiv, konsistent und entwicklerfreundlich zu sein. Du folgst REST-Best-Practices und bleibst dabei pragmatisch hinsichtlich realer Anforderungen. Ich brauche von dir das Design einer vollständigen API für Folgendes: ## Projektanforderungen API-Zweck: [BESCHREIBE, WAS DIE API TUT] Zielgruppe: [WER WIRD DIESE API NUTZEN] Kernressourcen: [LISTE DIE HAUPTENTITÄTEN AUF, z. B. Users, Products, Orders] Authentifizierungsmethode: [API KEY / OAuth 2.0 / JWT / usw.] Erwartete Skalierung: [ANFRAGEN PRO SEKUNDE / ANZAHL NUTZER] ## Erstelle ein vollständiges API-Design-Dokument: ### 1. API-ÜBERBLICK - Name und Version der API (z. B. v1) - Empfehlung zur Basis-URL-Struktur - Content-Type (JSON wird angenommen, Ausnahmen vermerken) - API-Stil (REST, mit Hinweisen zu eventuellen RPC-artigen Endpunkten) - Empfehlung zur Rate-Limiting-Strategie ### 2. AUTHENTIFIZIERUNG & AUTORISIERUNG Entwirf das Auth-System: - Details zur Authentifizierungsmethode - Token-Format und Lebenszyklus - Refresh-Token-Strategie (falls zutreffend) - Scopes-/Berechtigungsmodell - Beispiel für Auth-Header ``` Authorization: Bearer <token> X-API-Key: <api_key> ``` ### 3. RESSOURCEN-DESIGN Definiere für jede Kernressource: #### Ressource: [NAME] - Beschreibung - Beziehungen zu anderen Ressourcen - Format des eindeutigen Identifikators (UUID, Slug, Auto-Increment) **Endpunkte:** ``` GET /[resources] - List all (with pagination) GET /[resources]/:id - Get single resource POST /[resources] - Create new resource PUT /[resources]/:id - Full update PATCH /[resources]/:id - Partial update DELETE /[resources]/:id - Delete resource ``` **Datenschema:** ```json { "id": "string (uuid)", "created_at": "string (ISO 8601)", "updated_at": "string (ISO 8601)", // ... resource-specific fields } ``` **Feldtabelle:** | Feld | Typ | Erforderlich | Beschreibung | Einschränkungen | |------|-----|---------------|--------------|-------------------| ### 4. REQUEST-/RESPONSE-FORMATE **Standard-Erfolgsantwort:** ```json { "data": { ... }, "meta": { "request_id": "req_abc123", "timestamp": "2024-01-15T10:30:00Z" } } ``` **Listenantwort (mit Pagination):** ```json { "data": [ ... ], "pagination": { "total": 100, "page": 1, "per_page": 20, "total_pages": 5, "next_cursor": "eyJpZCI6MTAwfQ==", "has_more": true }, "meta": { ... } } ``` **Query-Parameter für Listen:** - `page` / `cursor` - Pagination - `per_page` / `limit` - Einträge pro Seite (max. 100) - `sort` - Feld zum Sortieren - `order` - asc/desc - `filter[field]` - Filterung - `include` - Einzubettende verwandte Ressourcen - `fields` - Sparse Fieldsets (Feldauswahl) ### 5. FEHLERBEHANDLUNG **Fehlerantwortformat:** ```json { "error": { "code": "VALIDATION_ERROR", "message": "Human readable message", "details": [ { "field": "email", "code": "INVALID_FORMAT", "message": "Email must be a valid email address" } ], "request_id": "req_abc123", "documentation_url": "https://api.example.com/docs/errors#VALIDATION_ERROR" } } ``` **Standard-Fehlercodes:** | HTTP-Status | Fehlercode | Beschreibung | |-------------|------------|--------------| | 400 | VALIDATION_ERROR | Anfragevalidierung fehlgeschlagen | | 401 | UNAUTHORIZED | Fehlende oder ungültige Authentifizierung | | 403 | FORBIDDEN | Gültige Authentifizierung, aber unzureichende Berechtigungen | | 404 | NOT_FOUND | Ressource existiert nicht | | 409 | CONFLICT | Konflikt beim Ressourcenstatus | | 422 | UNPROCESSABLE | Syntax gültig, aber semantischer Fehler | | 429 | RATE_LIMITED | Zu viele Anfragen | | 500 | INTERNAL_ERROR | Serverfehler | ### 6. VERSIONIERUNGSSTRATEGIE - URL-Versionierung: `/v1/resources` - Header-Versionierungsoption: `API-Version: 2024-01-15` - Deprecation-Richtlinie - Vorlage für Migrationsleitfaden ### 7. PAGINIERUNGS-DESIGN Wähle aus und dokumentiere: - Offset-basiert: `?page=2&per_page=20` - Cursor-basiert: `?cursor=eyJpZCI6MTAwfQ==` - Keyset: `?after_id=100` Füge Vor-/Nachteile des gewählten Ansatzes hinzu. ### 8. FILTERUNG & SUCHE Entwirf Query-Muster: ``` GET /products?filter[category]=electronics GET /products?filter[price][gte]=100&filter[price][lte]=500 GET /products?search=keyword GET /products?status=active,pending ``` ### 9. RATE LIMITING - Rate-Limit-Stufen (nach Plan/Auth-Level) - Zurückzugebende Header: - `X-RateLimit-Limit` - `X-RateLimit-Remaining` - `X-RateLimit-Reset` - Retry-After-Header bei 429 ### 10. WEBHOOKS (falls zutreffend) - Event-Typen - Payload-Format - Signaturverifizierung - Retry-Richtlinie ### 11. OPENAPI-SPEZIFIKATION Erstelle OpenAPI-3.0-YAML für die Kern-Endpunkte: ```yaml openapi: 3.0.0 info: title: [API Name] version: 1.0.0 paths: /[resource]: get: summary: List [resources] # ... complete specification ``` ### 12. SDK-ÜBERLEGUNGEN - Empfohlene SDK-Muster - Idiomatische Benennung für verschiedene Sprachen - Erwartungen an die Fehlerbehandlung - Pagination-Helfer Sorge dafür, dass alle Designs konsistent sind und den Industriestandards folgen. Begründe die Designentscheidungen. Füge curl-Beispiele für die wichtigsten Endpunkte hinzu.