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.
Mit Test Request können Sie eine Anfrage direkt aus der Referenz senden. Geben Sie im Feld Bearer Token einen REST-API-Schlüssel ein und wählen Sie in der Serverliste Ihren REST-Endpunkt aus. Die Anfrage wird für Ihren Workspace ausgeführt und ändert echte Daten. Verwenden Sie daher einen Schlüssel für einen Test-Workspace. Endpunkte, die PUT, PATCH oder DELETE verwenden, können nicht von der Dokumentationsseite aus gesendet werden und zeigen daher kein Test Request an. Kopieren Sie für diese Endpunkte 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
Wählen Sie auf jeder Seite eines REST API-Endpunkts in der Referenz Download OpenAPI Document aus, oder nutzen Sie den Download-Link am Ende der Seite. Jede Datei ist unter einer stabilen, öffentlichen URL im folgenden Format verfügbar:
https://www.braze.com/docs/assets/api/openapi/{spec_filename}.yaml
Jede Datei ist ein einzelnes, eigenständiges OpenAPI 3-Dokument für einen Endpunkt. Das Dokument enthält die Schemas für Anfrage und Antwort. Diese beschreiben genau, wie die Daten aufgebaut sind, die der Endpunkt annimmt und zurückgibt.
Warum die Schemas wertvoll sind
Ein Schema ist der strukturierte Vertrag für einen Endpunkt: Es definiert für jedes Feld den Namen, den Datentyp, ob das Feld erforderlich ist, die 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 dabei:
- Client-Code und SDKs generieren. Erstellen Sie typisierte Anfrage- und Antwortmodelle oder eine vollständige Client-Bibliothek in Ihrer bevorzugten Sprache, damit Sie Anfrage-Bodys nicht von Hand schreiben müssen.
- Anfragen und Antworten validieren. Prüfen Sie Payloads vor dem Senden anhand des Schemas und bestätigen Sie, dass Antworten Ihren Erwartungen entsprechen. So erkennen Sie Integrationsfehler frühzeitig.
- Die API simulieren. Richten Sie anhand der Spezifikation einen Mock-Server ein, damit Sie mit Braze-Endpunkten entwickeln und testen können, bevor Sie produktiven Integrationscode schreiben.
- In API-Clients importieren. Laden Sie die Spezifikation in Tools wie Postman oder Insomnia, um vorausgefü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, wann ein Feld hinzugefügt oder geändert wurde, und aktualisieren Sie dann Ihre Integration mit Zuversicht.
So verwenden Sie die Schemas
Die folgenden Anleitungen setzen voraus, dass Sie eine Spec-Datei von einer Endpunkt-Seite heruntergeladen haben.
Spec anzeigen und erkunden
Um eine Spec in einer strukturierten, interaktiven Ansicht zu lesen, verwenden Sie einen beliebigen OpenAPI-Viewer:
- Laden Sie die Spec-Datei 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 alle darin definierten Schemas zu durchsuchen.
Client oder Modelle generieren
Um ein Schema in typisierten Code in Ihrer Programmiersprache umzuwandeln, verwenden Sie einen OpenAPI-Generator:
- Installieren Sie einen Generator wie den OpenAPI Generator.
- Richten Sie den Generator auf die Spec-Datei aus und wählen Sie Ihre Zielsprache aus.
- Verwenden Sie in Ihrer Anwendung die generierten Anfrage- und Antwortmodelle oder den vollständigen Client, anstatt Request-Bodys manuell zu erstellen.
Payloads validieren
So stellen Sie sicher, dass ein Request-Body dem Vertrag des Endpunkts entspricht, bevor Sie ihn senden:
- Extrahieren Sie das Schema des Request-Bodys aus der Spec.
- Validieren Sie Ihre Payload mit einem JSON-Schema-Validator oder einer Bibliothek in Ihrer Programmiersprache gegen dieses Schema.
- Korrigieren 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
So erhalten Sie vorausgefüllte Anfragen und Inline-Feldbeschreibungen:
- Wählen Sie in Postman Import und dann die heruntergeladene Spec-Datei aus.
- Postman erstellt eine Collection 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.
Endpunkt mocken
So entwickeln Sie gegen einen Endpunkt, bevor Sie Live-Integrationscode schreiben:
- Laden Sie die Spec in ein Mocking-Tool wie Prism.
- Starten Sie den Mock-Server, der Antworten zurückgibt, die den Schemas der Spec entsprechen.
- Richten Sie Ihre Anwendung während der Entwicklung auf den Mock-Server aus und wechseln Sie dann zu Ihrem Live-REST-Endpunkt, sobald Sie bereit sind.