Ressourcen · 33
Entwickeln Sie API-Verträge weiter, ohne Kunden zu verlieren
Anfragen, Antworten und Fehler beschreiben; Testversionen und sichere Wiedergabe von Webhooks.
Aktualisiert · 2 min
Wozu dieser Leitfaden beiträgt
- Schreiben Sie den Vertrag
- Fehler klären
- Kompatibilität testen
- Ruhestand planen
Kurzcheck
- Welche Clients nutzen welche Operation?
- Haben Fehler stabile Typen und kohärente Status?
- Kann ein alter Kunde die Änderung tolerieren?
- Können Wiederholungsversuche eine Aktion duplizieren?
- Wie wird der Ruhestand bekannt gegeben und überprüft?
Schritt-für-Schritt-Anleitung
- 1
Inventarkonsumenten
Listen Sie Vorgänge, Clients, Verwendungen, Versionen und Besitzer auf. Trennen Sie die beobachtete Nutzung von den Annahmen, bevor Sie ein Feld ändern.
Liefergegenstand: Vertragsabhängigkeitskarte.
- 2
Beschreiben Sie Anfragen und Antworten
Pflegen Sie eine OpenAPI-Beschreibung mit Schemata, realistischen Beispielen, Erfolgs- und Fehlerantworten. Vergleichen Sie es mit dem laufenden Dienst.
Lieferinhalt: versionierte Vertrags- und Konformitätstests.
- 3
Fehler stabilisieren
Verwenden Sie HTTP-Status gemäß ihrer Semantik und, wo hilfreich, einem dokumentierten Problemtyp gemäß RFC 9457. Geben Sie keine Geheimnisse im Detail preis.
Lieferbar: geprüfter Fehlerkatalog.
- 4
Klassifizieren Sie die Änderung
Überprüfen Sie erforderliche Felder, Typen, Werte, Verhalten, Zeitüberschreitungen und Paginierung. Testen Sie alte Clients anhand repräsentativer Fälle mit der neuen Version.
Liefergegenstand: Kompatibilitätsmatrix und Versionsentscheidung.
- 5
Machen Sie Benachrichtigungen robust
Für Webhooks, Planauthentifizierung, ungeordnete Zustellung, Duplikate und Wiederholungsversuche. Machen Sie die Verarbeitung dort idempotent, wo Wiederholungen möglich sind.
Liefergegenstand: Wiederholungs- und Bestätigungsszenario.
- 6
Release mit Exit-Pfad
Migrationshinweise, Koexistenzzeitraum und Kontakte veröffentlichen. Messen Sie die Nutzung alter Versionen und stellen Sie sie erst ein, nachdem Sie die betroffenen Verbraucher überprüft haben.
Liefergegenstand: Migrationsplan und Ruhestandsnachweis.
Managementindikatoren
| Indikator | Was es misst | Erste Aktion |
|---|---|---|
| Vertrag | Beschriebene Vorgänge und entsprechendes Dienstverhalten | Divergenz beheben |
| Kompatibilität | Repräsentative Clients wurden vor der Änderung getestet | Fehlende Fälle hinzufügen |
| Fehler | Dokumentierte Typen ohne sensible Daten | Nachrichten und Schemata überarbeiten |
| Migration | Nutzung der alten Version mit Eigentümer | Verbleibende Kunden unterstützen |
Häufige Fallstricke
- Allein die Annahme einer Versionsnummer gewährleistet die Kompatibilität
- Dokumentation von nur 200 Antworten
- Rückgabe eines internen Trace oder Secrets bei einem Fehler
- Vorausgesetzt, Webhooks kommen einmal und in der richtigen Reihenfolge an
Häufig gestellte Fragen
Ersetzt OpenAPI das Testen?
Nein. Vergleichen Sie die Beschreibung mit tatsächlichen Reaktionen und Verbraucherbedürfnissen.
Erfordert jede Änderung eine neue Version?
Nein. Entscheiden Sie anhand der Kundenauswirkungen und des Vertragsverhaltens; Inkompatible Änderungen erfordern einen expliziten Plan.
Warum Tippfehler?
Sie bieten Kunden eine stabile Möglichkeit, Probleme zu unterscheiden und eine Aktion auszuwählen.
Offizielle Referenzen
Die Referenzen unterstützen die Methode. Passen Sie die Prüfungen an Ihren Kontext an; sie stellen keine Zertifizierung dar. Originalreferenztitel und Quelldokumente können in einer anderen Sprache verfasst sein.
