Durchsuchen Sie die Dokumentation
Haomai Technology AI Brain

Bereiten Sie eine API-Integration vor und überprüfen Sie den Vertrag

Bevor Sie ein Geschäftssystem verbinden, vereinbaren Sie Identität, Anfragen, Antworten, Fehlerbehandlung und Versionen. Der API-Vertrag bietet Entwicklern und Abnahmetestern eine gemeinsame Referenz. Auf den Marketingseiten und in den Screenshots der Benutzeroberfläche wird nicht angegeben, wie der Dienst aufgerufen wird.

Technischer Leitfaden · November 20263 Min. Lesezeit

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

VertragsgegenstandFragen, die es zu klären gilt
Identität und BerechtigungenLäuft der Vorgang als Benutzer oder als Anwendung? Wie wird der Umfang eingeschränkt?
AnfrageFeldtypen, erforderliche Felder, Größenbeschränkungen und Codierungsbeschränkungen
AntwortWie werden Ergebnisse, Quellen, Status und Abschluss dargestellt?
Zeitverhalten und AbbruchWie werden Zeitüberschreitungen, Abbrüche und lang laufende Aufgabenzustände gehandhabt?
FehlerWelche Fehler können wiederholt werden? Welche erfordern unterschiedliche Eingaben oder Berechtigungen?
VersionKompatibilitätsrichtlinie, Änderungsmitteilungen und Zeitplan für Abkündigungen

Führen Sie einen kleinen End-to-End-Test durch

  1. Konfigurieren Sie eine Identität mit den geringsten Rechten in einer isolierten Testumgebung. Halten Sie Zugangsdaten aus Frontend-Code und Beispiel-Repositories fern.
  2. Führen Sie einen erfolgreichen Anruf mit einer synthetischen Frage durch und behalten Sie eine redigierte Anfrage und Antwort bei.
  3. 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.
  4. 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.

Weiterführende Literatur

Versuchen Sie es mit „Berechtigungen“, „Datenquelle“, „Fertigung“ oder „API“.