Was macht api-design?
Entwerfe den Vertrag vor der Implementierung.
Wann verwenden
Verwende diese Fertigkeit, wenn der Benutzer:
- eine neue API oder Schnittstelle entwirft;
- einen bestehenden Vertrag ändert;
- Anfrage-/Antwortschemata definiert;
- Fehlerbehandlung, Authentifizierung, Paginierung oder Versionierung prüft;
- eine Integration mit einem Drittanbieter durchführt;
- fragt: „Wie sollte dieser Endpunkt aussehen?“.
1. Vertrag klären
Ermittle:
- wer die API aufruft: Frontend, Mobilgerät, Dienst, Partner, Agent;
- was der Aufrufer erreichen möchte;
- welche Daten ein- und ausgehen;
- was der Aufrufer niemals sehen darf;
- Latenz-, Volumen- und Zuverlässigkeitsanforderungen;
- Kompatibilitäts- und Versionierungsbeschränkungen.
2. Ressourcen und Aktionen modellieren
- Verwende Nomen für Ressourcen und explizite Aktionen für Operationen, die nicht CRUD sind.
- Halte URLs stabil und vorhersagbar.
- Bevorzuge einen klaren Weg, um eine Sache zu erledigen.
- Vermeide es, die Datenbankstruktur in den öffentlichen Vertrag durchsickern zu lassen.
- Definiere Identifikatoren, Eigentumsverhältnisse und Mandantenfähigkeit.
3. Schema definieren
Für jeden Endpunkt oder jede Schnittstelle:
- Methode und Pfad;
- Zweck;
- Authentifizierung und Berechtigungen;
- Pfad-, Abfrage- und Körperparameter;
- Validierungsregeln;
- Erfolgsantwort;
- Fehlerantworten;
- Idempotenz;
- Paginierung;
- Ratenbegrenzungen;
- Beispiele.
4. Fehler entwerfen
Jeder Fehler sollte enthalten:
- einen stabilen maschinenlesbaren Code;
- eine menschenlesbare Nachricht;
- das Feld oder den Parameter, der den Fehler verursacht hat;
- eine Anfrage-ID für den Support;
- keine Stack-Traces, Geheimnisse oder internen Pfade.
Verwende konsistente HTTP-Statuscodes. Gib nicht 200 für eine fehlgeschlagene Operation zurück.
5. Sicherheit und Datenschutz
- Authentifiziere jeden nicht öffentlichen Endpunkt.
- Autorisieren auf Objektebene, nicht nur auf Routenebene.
- Validiere alle Eingaben an der Grenze.
- Gib nur die Felder zurück, die der Aufrufer benötigt.
- Lege keine internen IDs offen, wenn sie Informationen preisgeben.
- Definiere Ratenbegrenzungen und Missbrauchskontrollen.
- Behandle Webhooks als nicht vertrauenswürdige Eingaben.
6. Weiterentwicklungsfähigkeit
- Füge Felder hinzu, anstatt ihre Bedeutung zu ändern.
- Behalte alte Felder bei, bis Clients migriert sind.
- Versioniere nur, wenn nötig.
- Dokumentiere die Abkündigung und Migration.
- Vermeide breaking changes in Nebenversionen.
7. Ausgabeformat
## Vertrag
### `METHODE /pfad`
**Zweck:** <was es tut>
**Authentifizierung:** <wer es aufrufen kann>
**Idempotenz:** <ja/nein und Schlüssel>
#### Anfrage
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
#### Antwort
```json
{}
```
#### Fehler
| Status | Code | Wann |
|---|---|---|
#### Beispiel
```http
METHODE /pfad
...
```
## Kompatibilität
- <was sich ändern kann>
- <was eine neue Version erfordert>
## Offene Fragen
- <Frage>
Regeln
- Erfinde keine Geschäftsregeln.
- Lege keine internen Felder ohne Grund offen.
- Verwende keine inkonsistente Namensgebung zwischen Endpunkten.
- Entwerfe keine öffentliche API basierend auf dem aktuellen Datenbankschema.
- Lasse kein Fehler- und Leerzustandsverhalten aus.
- Wenn die API mit Geld, Gesundheit oder personenbezogenen Daten umgeht, ist eine Sicherheitsüberprüfung erforderlich.
Qualitätsprüfungen
- Der Aufrufer und die Aufgabe sind klar.
- Das Schema ist vollständig.
- Fehler sind konsistent und sicher.
- Authentifizierung und Berechtigungen auf Objektebene sind definiert.
- Paginierung und Grenzen sind definiert.
- Kompatibilität ist adressiert.
- Beispiele sind gültig.