API-Design-Review
Überblick
Beurteilen Sie eine API aus Client-Sicht: vorhersagbare Namen, ehrliche Statuscodes, ein einheitliches Fehlerformat, sichere Wiederholungen und keine überraschenden Breaking Changes. Jede Feststellung verweist auf einen konkreten Routen und zeigt das korrigierte Design.
Methode
- Inventur. Listen Sie jeden Endpunkt als
METHODE /pfad → Statuscodes → Anfrage-/Antwortformauf. Lesen Sie Routen, Controller, OpenAPI-Dateien und DTOs. - Prüfen Sie jeden Endpunkt anhand der nachstehenden Regeln.
- Prüfen Sie die API als Ganzes: Konsistenz zwischen den Endpunkten ist wichtiger als eine einzelne Entscheidung.
- Änderungen: Wenn Sie einen Diff prüfen, vergleichen Sie alte und neue Verträge und markieren Sie alles, das bestehende Clients bricht.
- Bericht unter Verwendung des folgenden Vertrags.
Regeln
| Bereich | Regel |
|---|---|
| Ressourcen | Pluralnomen, keine Verben: POST /orders, nicht /createOrder. Nur bei echter Besitzerbeziehung verschachteln: /users/{id}/orders. |
| Methoden | GET liest und ist sicher. POST erstellt. PUT ersetzt. PATCH aktualisiert teilweise. DELETE löscht. Niemals den Zustand mit GET ändern. |
| Statuscodes | 200 OK, 201 Created (+ Location), 204 No Content, 400 ungültige Eingabe, 401 nicht authentifiziert, 403 nicht erlaubt, 404 fehlt, 409 Konflikt, 422 Validierung, 429 Ratenbegrenzung, 5xx nur für Serverfehler. Niemals 200 mit {"error": ...}. |
| Fehler | Ein einheitliches Format überall, z. B. RFC 9457: { "type", "title", "status", "detail", "errors": [{ "field", "message" }] }. Keine Stacktraces oder SQL in Antworten. |
| Namensgebung | Einheitliche Schreibweise für JSON-Felder (camelCase oder snake_case), konsistente IDs, ISO 8601 UTC-Zeitstempel, Geld als ganze Zahl in Untereinheiten oder Dezimalstring plus Währung. |
| Sammlungen | Jede Liste paginieren (Cursor bevorzugt bei großen oder sich ändernden Daten), Seitengröße begrenzen, nächsten Cursor oder Links zurückgeben. Filtern und Sortieren über Query-Parameter. |
| Idempotenz | Wiederholte POSTs, die Zahlungen, Bestellungen oder E-Mails erstellen, akzeptieren einen Idempotency-Key. PUT und DELETE sind von Haus aus idempotent. |
| Versionierung | Eine klare Strategie (/v1-Pfad oder Header). Breaking Changes erfordern eine neue Version. |
| Breaking Changes | Entfernen oder Umbenennen von Feldern, Ändern von Typen, erforderliche optionale Eingaben machen, Statuscodes oder Fehlerformat ändern, Validierung verschärfen. |
| Sicherheit | Authentifizierung auf jeder nicht-öffentlichen Route, objektbezogene Besitzprüfungen, Ratenbegrenzung auf Auth- und teuren Routen, keine sensiblen Daten in URLs. |
| Leistung | Keine unbegrenzten Antworten, fields- oder sparse-responses für schwere Objekte unterstützen, ETag oder Cache-Control für cachebare GETs. |
Ausgabevertrag
Beginnen Sie mit: N Endpunkte geprüft, M Feststellungen (X breaking). Dann, höchste Auswirkung zuerst:
### [Breaking | High | Medium | Low] Titel
- Endpunkt: METHODE /pfad (datei:zeile)
- Problem: was ein Client erlebt
- Fix: die korrigierte Route, der Statuscode oder das JSON-Format
Schließen Sie mit einer kurzen Konsistenzzusammenfassung (Namensgebung, Fehlerformat, Paginierung, Versionierung: konsistent oder nicht) und, wenn von Grund auf neu entworfen, der vorgeschlagenen Endpunkttabelle.
Häufige Fehler
- Endpunkte einzeln prüfen und übersehen, dass zwei in der Schreibweise oder im Fehlerformat nicht übereinstimmen.
- Ein Redesign empfehlen, wenn eine abwärtskompatible Ergänzung ausreichen würde.
- Eine Änderung als sicher bezeichnen, weil der Server-Code noch funktioniert: Prüfen Sie, was bestehende Clients senden und erwarten.
- 500 für Validierungsfehler oder 404 für Berechtigungsfehler verwenden, ohne bewusst zu entscheiden.
Erstellt von Wageesha Tripathi · LinkedIn · E-Mail · Weitere Skills