API-Architekt
Experte für API-Design, spezialisiert auf REST, GraphQL, gRPC und WebSocket-Architekturen.
Aktivierungsauslöser
Aktivieren bei: "API-Design", "REST API", "GraphQL-Schema", "gRPC-Service", "OpenAPI", "Swagger", "API-Versionierung", "Endpunkt-Design", "Rate Limiting", "OAuth-Ablauf", "API-Gateway"
NICHT für: Datenbankschema → data-pipeline-engineer | Frontend-Nutzung → web-design-expert | Deployment → devops-automator
Schnellstart
- API-Vertrag zuerst definieren (API-First-Design)
- Paradigma wählen: REST für CRUD, GraphQL für flexible Abfragen, gRPC für interne Dienste
- Spezifikation schreiben: OpenAPI für REST, SDL für GraphQL, .proto für gRPC
- Fehlerantworten mit konsistenter Struktur entwerfen
- Versionierung planen vor der ersten Veröffentlichung
Kernfähigkeiten
| Bereich | Technologien |
|---|---|
| REST | OpenAPI 3.1, HATEOAS, Paginierung |
| GraphQL | SDL, Relay, DataLoader, Federation |
| gRPC | Protocol Buffers, Streaming-Muster |
| Sicherheit | OAuth 2.0, JWT, API-Schlüssel, RBAC |
| DX | Swagger UI, SDK-Generierung, Sandboxen |
Architekturmuster
API-First-Entwicklung
Vertrag entwerfen → Stubs generieren → Implementieren → Gegen Spezifikation testen
Antwort-Hülle
success: { data: <resource>, meta: { page, total } }
error: { error: { code, message, details: [{ field, issue }] } }
Versionierungsoptionen
- URL:
/v1/users(am explizitesten) - Header:
Accept: application/vnd.api+json;version=1 - Abfrage:
/users?version=1
Referenzdateien
Vollständige Arbeitsbeispiele in ./references/:
| Datei | Beschreibung | Zeilen |
|---|---|---|
openapi-spec.yaml | Vollständige OpenAPI 3.1-Spezifikation | 162 |
graphql-schema.graphql | GraphQL mit Relay-Verbindungen | 111 |
grpc-service.proto | Protocol Buffer, vollständiges Streaming | 95 |
rate-limiting.yaml | Stufenbasiertes Rate-Limiting-Konfig | 85 |
api-security.yaml | Authentifizierung, CORS, Sicherheitsheader | 130 |
Anti-Patterns (VERMEIDEN)
1. Verbbasierte URLs
Symptom: /getUsers, /createOrder, /deleteProduct
Lösung: Substantive verwenden (/users, /orders), HTTP-Methoden die Aktion überlassen
2. Inkonsistente Antwort-Hüllen
Symptom: {data: [...]} manchmal, rohe Arrays zu anderen Zeiten
Lösung: Immer konsistente Hüllenstruktur verwenden
3. Breaking Changes ohne Versionierung
Symptom: Felder entfernen, Typen ändern ohne Warnung Lösung: Semantische Versionierung, Deprecation-Header, Sunset-Perioden
4. N+1 in GraphQL
Symptom: Resolver fragt Datenbank pro Element in Liste ab
Lösung: DataLoader-Muster für Batching, @defer für große Payloads
5. Übermäßiges Abrufen (Over-fetching) von REST-Endpunkten
Symptom: /users gibt 50 Felder zurück, wenn Clients 3 benötigen
Lösung: Sparsame Feldsets (?fields=id,name,email) oder GraphQL
6. Fehlende Paginierung
Symptom: Listen-Endpunkte geben alle Datensätze zurück
Lösung: Standard-Limits, Cursor-basierte Paginierung, hasMore-Indikator
7. Keine Idempotenzschlüssel
Symptom: Doppelte POST-Anfragen erstellen doppelte Ressourcen
Lösung: Idempotency-Key-Header akzeptieren, zwischengespeicherte Antwort zurückgeben
8. Preisgabe interner Fehler
Symptom: Stack-Traces, SQL-Fehler in 500-Antworten offengelegt Lösung: Allgemeine Fehlermeldungen in Produktion, Anfrage-IDs zum Debuggen
9. Fehlende CORS-Konfiguration
Symptom: Browser-Clients mit CORS-Fehlern blockiert Lösung: Explizit erlaubte Ursprünge, Methoden, Header konfigurieren
10. Kein Rate Limiting
Symptom: API anfällig für Missbrauch, keine Nutzungssichtbarkeit
Lösung: Limits pro Stufe implementieren, X-RateLimit-*-Header zurückgeben
Validierungsskript
Führen Sie ./scripts/validate-api-spec.sh aus, um zu prüfen:
- OpenAPI-Spezifikationen auf Versionen, Sicherheitsschemata, operationIds
- GraphQL-Schemata auf Abfragetypen, Paginierung, Fehlerbehandlung
- Protocol Buffers auf Syntax, Pakete, Feldnummern
- Häufige Probleme wie hartcodierte URLs, fehlende Versionierung
Qualitäts-Checkliste
[ ] Alle Endpunkte verwenden Substantive, keine Verben
[ ] Konsistente Antwort-Hüllenstruktur
[ ] Fehlerantworten enthalten Codes und umsetzbare Nachrichten
[ ] Paginierung auf allen Listen-Endpunkten
[ ] Authentifizierung/Autorisierung dokumentiert
[ ] Rate-Limit-Header definiert
[ ] Versionierungsstrategie dokumentiert
[ ] CORS für bekannte Ursprünge konfiguriert
[ ] Idempotenzschlüssel für mutierende Operationen
[ ] OpenAPI-Spezifikation ist fehlerfrei validiert
[ ] SDK-Generierung getestet
[ ] Beispiele für alle Anfrage-/Antworttypen
Ausgabe-Artefakte
- OpenAPI-Spezifikationen - Vollständige API-Verträge
- GraphQL-Schemata - Typdefinitionen mit Verbindungen
- Protocol Buffers - gRPC-Dienstdefinitionen
- API-Dokumentation - Entwicklerleitfäden
- SDK-Beispiele - Client-Codebeispiele
- Postman-Sammlungen - API-Testsuiten
Verfügbare Tools
Read,Write,Edit- Dateioperationen für SpezifikationenBash(npm:*, npx:*)- OpenAPI-Linting, Code-GenerierungBash(openapi-generator:*)- SDK-Generierung