Beginnen Sie mit dem Vertrag für Ihre Veröffentlichung
Besorgen Sie sich die API-Dokumentation für Ihre Bereitstellung und überprüfen Sie die Dienstadresse, die Authentifizierungsmethode, die Anforderungs- und Antwortstrukturen sowie die verfügbaren Funktionen. OpenAPI ist ein Standard zur Beschreibung von HTTP-API-Operationen, Parametern und Datenmodellen. Für die eigentliche Integration nutzen Sie den dem Produkt beiliegenden Vertrag.
In diesem Vorbereitungsleitfaden werden nicht verifizierte Haomai Technology Brain-Endpunkte, Authentifizierungsfelder und SDK-Paketnamen weggelassen. Bevor Sie Code schreiben, müssen sich der Kunde und die Serviceteams auf denselben Vertrag und das darin enthaltene Release einigen.
Mindestangaben für den API-Vertrag
| Vertragsgegenstand | Fragen, die es zu klären gilt |
|---|---|
| Identität und Berechtigungen | Läuft der Vorgang als Benutzer oder als Anwendung? Wie wird der Umfang eingeschränkt? |
| Anfrage | Feldtypen, erforderliche Felder, Größenbeschränkungen und Codierungsbeschränkungen |
| Antwort | Wie werden Ergebnisse, Quellen, Status und Abschluss dargestellt? |
| Zeitverhalten und Abbruch | Wie werden Zeitüberschreitungen, Abbrüche und lang laufende Aufgabenzustände gehandhabt? |
| Fehler | Welche Fehler können wiederholt werden? Welche erfordern unterschiedliche Eingaben oder Berechtigungen? |
| Version | Kompatibilitätsrichtlinie, Änderungsmitteilungen und Zeitplan für Abkündigungen |
Führen Sie einen kleinen End-to-End-Test durch
- Konfigurieren Sie eine Identität mit den geringsten Rechten in einer isolierten Testumgebung. Halten Sie Zugangsdaten aus Frontend-Code und Beispiel-Repositories fern.
- Führen Sie einen erfolgreichen Anruf mit einer synthetischen Frage durch und behalten Sie eine redigierte Anfrage und Antwort bei.
- Decken Sie ungültige Eingaben, unzureichende Berechtigungen, Zeitüberschreitungen und Abbrüche ab. Stellen Sie sicher, dass der Client einen eindeutigen Fehlerstatus und kein leeres Ergebnis anzeigt.
- Testen Sie das Verhalten fehlender und unbekannter Felder anhand des Vertrags, bevor Sie die Geschäftsschnittstelle verbinden.
Entwerfen Sie Wiederholungsversuche rund um die Auswirkung einer Operation
Eine unterbrochene Netzwerkverbindung lässt nicht erkennen, ob der Server den Vorgang ausgeführt hat. Bestätigen Sie bei Aktionen, die möglicherweise Nebenwirkungen haben, die Idempotenz und erfahren Sie, wie der Aufgabenstatus abgefragt wird, bevor Sie es erneut versuchen. Legen Sie für schreibgeschützte Abfragen angemessene Grenzwerte, Backoff- und Stornierungsbedingungen fest.
Notieren Sie bei der Abnahme die Vertragsversion, die Client-Version, Testfälle und bekannte Grenzen. Validieren Sie bei nachfolgenden Upgrades dieselben Fälle, bevor Sie den Datenverkehr schrittweise erhöhen.
