Braze OpenAPI-Spezifikationen verwenden
Dieser Referenzartikel erklärt, wie Braze OpenAPI-Spezifikationen für seine REST-API-Endpunkte veröffentlicht und wie Sie die Schemas in diesen Spezifikationen nutzen können, um Ihre Entwicklungsworkflows zu beschleunigen.
Jede Braze REST-API-Endpunktseite rendert eine interaktive Referenz, die aus einer OpenAPI-Spezifikation generiert wird. Die Referenz zeigt die Parameter des Endpunkts, den Request Body, Antwortschemas und Beispielantworten in einem konsistenten, strukturierten Format. Jede Spezifikation ist zugleich eine maschinenlesbare Datei, die Sie herunterladen und direkt in Ihren eigenen Tools verwenden können.
Die Referenz auf jeder Endpunktseite ist schreibgeschützt. Sie sendet keine Live-Anfragen von der Dokumentationsseite. Um einen Endpunkt aufzurufen, kopieren Sie das generierte cURL-Beispiel oder verwenden Sie die heruntergeladene Spezifikation in Ihrem eigenen Client, wie unter So verwenden Sie die Schemas beschrieben.
Wo Sie eine Spezifikation finden
Auf jeder REST-API-Endpunktseite finden Sie den Abschnitt Endpoint reference. Um die Rohspezifikation zu öffnen, verwenden Sie die Option zum Herunterladen der Spezifikation in diesem Abschnitt. Jede Datei befindet sich unter einer stabilen, öffentlichen URL im folgenden Format:
https://www.braze.com/docs/assets/api/openapi/{spec_filename}.yaml
Jede Datei ist ein eigenständiges OpenAPI-3-Dokument für einen einzelnen Endpunkt. Das Dokument enthält die Anfrage- und Antwortschemas, die die genaue Struktur der Daten beschreiben, die der Endpunkt akzeptiert und zurückgibt.
Warum die Schemas wertvoll sind
Ein Schema ist der strukturierte Vertrag für einen Endpunkt: Es definiert den Namen jedes Felds, den Datentyp, ob das Feld erforderlich ist, seine zulässigen Werte und wie Objekte verschachtelt sind. Da dieser Vertrag maschinenlesbar ist, können Sie sich darauf verlassen, anstatt Anfrage- und Antwortstrukturen manuell zu kopieren. Informationen zu den wiederverwendbaren Objekten und Filtern, die viele Endpunkte gemeinsam nutzen, finden Sie unter Objekte und Filter. Die Schemas helfen Ihnen bei Folgendem:
- Client-Code und SDKs generieren. Erzeugen Sie typisierte Anfrage- und Antwortmodelle oder eine vollständige Client-Bibliothek in Ihrer bevorzugten Sprache, damit Sie Anfrage-Bodys nicht manuell schreiben müssen.
- Anfragen und Antworten validieren. Prüfen Sie Payloads vor dem Senden gegen das Schema und bestätigen Sie, dass Antworten dem entsprechen, was Sie erwarten – so erkennen Sie Integrationsfehler frühzeitig.
- Die API mocken. Erstellen Sie einen Mock-Server aus der Spezifikation, um gegen Braze-Endpunkte zu entwickeln und zu testen, bevor Sie Live-Integrationscode schreiben.
- In API-Clients importieren. Laden Sie die Spezifikation in Tools wie Postman oder Insomnia, um vorgefüllte Anfragen, Parameterbeschreibungen und Autovervollständigung zu erhalten.
- Integrationen synchron halten. Vergleichen Sie eine gespeicherte Kopie einer Spezifikation mit der aktuellen Version, um zu erkennen, wenn ein Feld hinzugefügt oder geändert wurde, und aktualisieren Sie Ihre Integration dann mit Zuversicht.
So verwenden Sie die Schemas
Die folgenden Anweisungen setzen voraus, dass Sie eine Spezifikationsdatei von einer Endpunkt-Seite heruntergeladen haben.
Eine Spezifikation anzeigen und erkunden
Um eine Spezifikation in einer strukturierten, interaktiven Ansicht zu lesen, verwenden Sie einen beliebigen OpenAPI-Viewer:
- Laden Sie die Spezifikationsdatei für den gewünschten Endpunkt herunter.
- Öffnen Sie den Swagger Editor oder einen ähnlichen Viewer.
- Fügen Sie die Datei ein oder laden Sie sie hoch, um die Operation, ihre Parameter und jedes definierte Schema zu durchsuchen.
Einen Client oder Modelle generieren
Um ein Schema in typisierten Code in Ihrer Sprache umzuwandeln, verwenden Sie einen OpenAPI-Generator:
- Installieren Sie einen Generator wie den OpenAPI Generator.
- Verweisen Sie den Generator auf die Spezifikationsdatei und wählen Sie Ihre Zielsprache aus.
- Verwenden Sie die generierten Anfrage- und Antwortmodelle oder den vollständigen Client in Ihrer Anwendung, anstatt Anfragekörper manuell zu erstellen.
Ihre Payloads validieren
Um zu bestätigen, dass ein Anfragekörper dem Vertrag des Endpunkts entspricht, bevor Sie ihn senden:
- Extrahieren Sie das Anfragekörper-Schema aus der Spezifikation.
- Verwenden Sie einen JSON-Schema-Validator oder eine Bibliothek in Ihrer Sprache, um Ihren Payload gegen dieses Schema zu validieren.
- Beheben Sie alle Felder, die der Validator als fehlend, falsch typisiert oder außerhalb des zulässigen Bereichs markiert.
In Postman oder einen anderen Client importieren
Um vorbefüllte Anfragen und Inline-Feldbeschreibungen zu erhalten:
- Wählen Sie in Postman Import aus und wählen Sie dann die heruntergeladene Spezifikationsdatei.
- Postman erstellt eine Sammlung mit dem Endpunkt, seinen Parametern und Beispielwerten.
- Fügen Sie Ihren REST-API-Schlüssel und den gewünschten REST-Endpunkt hinzu und senden Sie dann Ihre Anfrage.
Den Endpunkt mocken
Um gegen einen Endpunkt zu entwickeln, bevor Sie Live-Integrationscode schreiben:
- Laden Sie die Spezifikation in ein Mocking-Tool wie Prism.
- Starten Sie den Mock-Server, der Antworten zurückgibt, die den Schemas der Spezifikation entsprechen.
- Verweisen Sie Ihre Anwendung während der Entwicklung auf den Mock-Server und wechseln Sie dann zu Ihrem Live-REST-Endpunkt, wenn Sie bereit sind.