Datenmodelle
Teil von APIs und Webhooks in Workflows
Antwortdaten einer API vor der Zuordnung prüfen
HTTP-Status, JSON-Struktur, Kennungen und paginierte Ergebnisse prüfen, bevor API-Werte in einen Workflow übernommen werden.
Ordnen Sie eine API-Antwort erst einem Datensatz oder Feld im Zielsystem zu, wenn Status, Datenform und fachliche Bedeutung zur angefragten Operation passen. Eine gültige JSON-Antwort kann das falsche Objekt, einen fehlenden Wert oder nur einen Teil der Ergebnisse enthalten.
Status und Antwortkörper prüfen
Halten Sie für einen geeigneten Testfall die API-Operation, den HTTP-Status, relevante Header und den tatsächlichen Antwortkörper zusammen fest. Entfernen Sie Zugangsdaten und vertrauliche Inhalte aus Beispielen, die weitergegeben werden. Prüfen Sie in der Dokumentation der konkreten Operation, welche Antwort bei Erfolg und bei Fehlern vorgesehen ist.
Der HTTP-Status allein sagt nicht, welche Felder übernommen werden dürfen. Prüfen Sie anhand der Dokumentation, ob eine Antwort einen Antwortkörper erwarten lässt. Ein Workflow darf ohne Antwortkörper keinen JSON-Datensatz erwarten. Einen Fehlerkörper darf er umgekehrt nicht wie einen erfolgreichen Geschäftsdatensatz zuordnen.
Wenn Inhalt geliefert wird, prüfen Sie, ob sein Content-Type zur erwarteten Verarbeitung passt.
Wichtige HTTP-Statuscodes bei API-Aufrufen
- 200OK — Erfolgreiche Anfrage, Antwort enthält Daten
- 400Bad Request — Fehler in der Anfrage (z. B. falsches Format)
- 404Not Found — Gesuchtes Objekt existiert nicht
- 500Internal Server Error — Server-Fehler – keine Daten lieferbar
Datenform und Feldregeln festlegen
Für eine hypothetische Materialanforderung könnte eine kleine Zuordnung so aussehen:
| Zielfeld | Erwartete Quelle | Prüfung vor der Zuordnung |
|---|---|---|
| Vorgangskennung | id des erwarteten Objekts | Gehört die Kennung zum angefragten Vorgang? |
| Bearbeitungsstatus | status | Ist der Wert für diesen Schritt zulässig? |
| Menge | quantity | Hat der Wert den erwarteten Typ und erfüllt er die Fachregel? |
Die Feldnamen sind Beispiele. Eine echte API kann einen Datensatz als Objekt, in einem Array oder in einer verschachtelten Struktur liefern.
JSON unterscheidet unter anderem Zeichenfolgen, Zahlen, null, Objekte und Arrays. Die Zeichenfolge 0 hat daher eine andere Datenform als die Zahl 0. Ein fehlendes Feld ist nicht dasselbe wie ein ausdrücklich geliefertes null; wie beides fachlich behandelt wird, muss die Schnittstelle festlegen.
Bestimmen Sie für jedes benötigte Feld, was bei fehlenden, leeren oder unerwarteten Werten geschieht. Wenn ein Wert nicht verlässlich zugeordnet werden kann, bleibt der Fall sichtbar ungeklärt. Ein still eingesetzter Ersatzwert könnte später wie eine echte API-Angabe wirken.
Datenformen in JSON – Unterschiede und Bedeutung
- Zeichenfolge `0`
- Text, nicht Zahl – z. B. für IDs
- Zahl 0
- Numerisch – für Berechnungen geeignet
- Feld fehlt
- Kein Wert vorhanden – nicht gleich `null`
- `null` im JSON
- Ausdrücklich leer – fachlich definiert
Identität und Umfang kontrollieren
Bei einem Abruf eines einzelnen Vorgangs vergleichen Sie die gelieferte Kennung mit der angefragten, soweit die API sie zurückgibt. Bei einer Liste prüfen Sie Filter und weitere Seiten. GitHubs REST-API kann Ergebnisse auf mehrere Seiten verteilen und verweist gegebenenfalls über den link-Header auf die nächste Seite. Für andere APIs gelten deren eigene Seitensignale.
Prüfen Sie bei Zeit-, Mengen- und Betragsfeldern dokumentierte Einheit, Format und Bedeutung vor einer Umwandlung. Aus einem Feldnamen allein lässt sich weder die Zeitzone eines Zeitpunkts noch die Einheit eines Betrags sicher ableiten. Ist die Bedeutung nicht eindeutig, bleibt die Feldzuordnung offen.
Grenzfälle vor dem Schreiben durchgehen
Notieren Sie je Zielfeld Quelle, erlaubte Werte, nötige Umwandlung und Reaktion auf Abweichungen. Gehen Sie mit unkritischen Beispielen eine vollständige Antwort, ein fehlendes Pflichtfeld, null, einen falschen Typ, einen Fehlerstatus, eine Antwort ohne Antwortkörper und mehrere Ergebnisse durch. Halten Sie jeweils den erwarteten Zielzustand fest. Erst eine eindeutig geprüfte Zuordnung sollte einen Schreibschritt auslösen.
