OpenAPI-Schemas zur Anfrage-Validierung verwenden

Dieser Referenzartikel erklärt, was OpenAPI-Schemas sind, wie sie funktionieren und wie Sie sie verwenden können, um zu bestätigen, dass Ihre Anfragen an Braze REST API-Endpunkte korrekt strukturiert sind, bevor Sie sie absenden.

Jede Braze REST API-Endpunktseite rendert eine interaktive Referenz, die aus einer OpenAPI-Spezifikation generiert wird. Jede Spezifikation enthält ein Schema: eine präzise, maschinenlesbare Beschreibung der Daten, die ein Endpunkt akzeptiert und zurückgibt. Sie können dieses Schema verwenden, um Ihre Anfragen zu validieren und so strukturelle Fehler in Ihren eigenen Tools zu erkennen, anstatt sie erst durch einen fehlgeschlagenen API-Aufruf zu entdecken.

Einen umfassenderen Überblick darüber, wie Braze diese Spezifikationen veröffentlicht und welche anderen Workflows sie unterstützen, finden Sie unter Braze OpenAPI-Spezifikationen verwenden.

Was ein OpenAPI-Schema ist

Ein Schema ist der Vertrag für die Daten eines Endpunkts. In einem OpenAPI-Dokument definiert das Schema Object jedes Feld, das ein Endpunkt verwendet, einschließlich des Feldnamens, des Datentyps, ob es erforderlich ist, seiner zulässigen Werte und wie verschachtelte Objekte und Arrays strukturiert sind.

OpenAPI-Schemas basieren auf JSON Schema, einem weit verbreiteten Standard zur Beschreibung der Struktur von JSON-Daten. Da der Vertrag in einem standardisierten, maschinenlesbaren Format ausgedrückt wird, können Sie eine Payload mit gängigen Tools validieren, anstatt Felder manuell zu prüfen. Weitere Informationen zu den zugrunde liegenden Konzepten finden Sie unter Learn OpenAPI und Understanding JSON Schema.

Funktionsweise von Schemas

Ein Schema beschreibt Daten mithilfe einer kleinen Anzahl von Grundbausteinen. Die gängigsten sind:

• Typ. Der Datentyp eines Werts, z. B. string, integer, number, boolean, array oder object. Siehe Datentypen in der Swagger-Dokumentation.
• Pflichtfelder. Eine Liste der Eigenschaften, die vorhanden sein müssen, damit die Daten gültig sind.
• Einschränkungen. Regeln, die eingrenzen, welche Werte zulässig sind, z. B. ein enum zulässiger Werte, ein format (beispielsweise date-time), ein String-Muster oder Minimal- und Maximalwerte.
• Verschachtelte Struktur. Objekte können andere Objekte enthalten, und Arrays deklarieren das Schema der darin enthaltenen Elemente, sodass ein Schema auch tief verschachtelte Payloads beschreiben kann.

Ein Validator liest diese Regeln und vergleicht Ihre Daten damit. Wenn ein Pflichtfeld fehlt, ein Wert den falschen Typ hat oder ein Wert außerhalb der zulässigen Menge liegt, meldet der Validator das spezifische Problem. Die JSON-Schema-Spezifikation definiert dieses Validierungsverhalten im Detail.

Wie ein Schema eine gültige Anfrage definiert

Bei Endpunkten, die einen Anfragekörper akzeptieren, beschreibt das Anfragekörper-Schema der Spezifikation genau, wie ein gültiger Payload aussieht. Viele Braze-Endpunkte verwenden dieselben Anfragestrukturen, z. B. Nutzer:innen-Bezeichner, Messaging-Objekte und Zielgruppenfilter. Eine feldweise Referenz zu diesen gemeinsam genutzten Strukturen finden Sie unter Objekte und Filter. Betrachten Sie ein vereinfachtes Schema für eine Anfrage, die einen String external_id und einen Integer points erfordert, wobei points nicht negativ sein darf:

1
2
3
4
5
6
7
8

{
  "type": "object",
  "required": ["external_id", "points"],
  "properties": {
    "external_id": { "type": "string" },
    "points": { "type": "integer", "minimum": 0 }
  }
}

Ein Payload, der dieses Schema erfüllt, ist gültig:

1

{ "external_id": "user-123", "points": 50 }

Jeder der folgenden Payloads ist ungültig, und ein Validator erklärt warum:

• { "points": 50 } lässt das erforderliche Feld external_id aus.
• { "external_id": "user-123", "points": "50" } sendet points als String statt als Integer.
• { "external_id": "user-123", "points": -5 } sendet einen Wert, der die minimum-Einschränkung verletzt.

Indem Sie zuerst das Schema lesen, wissen Sie, welche Felder Sie senden müssen, welchen Typ jeder Wert haben muss und welche Werte zulässig sind – bevor Sie einen einzigen Aufruf tätigen.

Eine Anfrage gegen ein Schema validieren

So validieren Sie einen Payload gegen das Schema eines Endpunkts:

1. Laden Sie die Spezifikation für den gewünschten Endpunkt herunter. Jede Spezifikation ist unter einer stabilen, öffentlichen URL im Format https://www.braze.com/docs/assets/api/openapi/{spec_filename}.yaml verfügbar.
2. Extrahieren Sie das Request-Body-Schema aus der Spezifikation.
3. Validieren Sie Ihren Payload gegen dieses Schema mit einem JSON-Schema-Validator, z. B. Ajv für JavaScript, oder einer anderen Bibliothek aus der JSON Schema Tools-Liste für Ihre Sprache.
4. Beheben Sie alle Felder, die der Validator als fehlend, falsch typisiert oder außerhalb des gültigen Bereichs markiert, und senden Sie dann Ihre Anfrage.

Sie können auch ganze Spezifikationen mit Tools wie Spectral linten und validieren oder typisierte Anfrage-Modelle mit OpenAPI Generator generieren, sodass Ihr Code von vornherein gültige Payloads erzeugt. Schritt-für-Schritt-Workflows, die diese Spezifikationen verwenden, finden Sie unter So verwenden Sie die Schemas.

Warum Schema-Validierung wichtig ist

Die Validierung von Anfragen anhand des Schemas hilft Ihnen:

• Fehler früher erkennen. Finden Sie fehlende oder falsch geschriebene Felder in Ihrer eigenen Umgebung, anstatt erst durch einen abgelehnten API-Aufruf darauf aufmerksam zu werden.
• Fehlgeschlagene Aufrufe reduzieren. Senden Sie von Anfang an korrekt formatierte Anfragen, was Wiederholungsversuche und Fehlerbehebung verringert.
• Mit Zuversicht integrieren. Verlassen Sie sich auf einen einzigen, maschinenlesbaren Vertrag, anstatt Anfrageformate manuell zu kopieren.
• Prüfungen automatisieren. Fügen Sie Validierung zu Ihren Tests oder Ihrer CI-Pipeline hinzu, damit Integrationen korrekt bleiben, wenn sich Ihr Code ändert.

Verwandte Ressourcen

• braze-dokumentation
• externe referenzen