Zum Inhalt springen
Szenera DeveloperHandbuch
Änderungen › Nachverfolgen › Die Spezifikation gegen Ihren Stand vergleichen
Kapitel

Die Spezifikation gegen Ihren Stand vergleichen

openapi.json datiert ablegen, bei jedem Zug neu laden, Pfade, Pflichtfelder und Fehlercodes vergleichen — Seite und eigene Umgebung nebeneinander.

3 Minuten LesezeitÄnderungenStand: 25.10.2026

Auf dieser Seite

Bevor Sie loslegen

Für wen
Wer eine Integration betreibt und nach jedem Zug prüfen will, ob sie noch passt.
Voraussetzung
curl, jq und eine Bash (Schritt 5 nutzt <( … ), das eine POSIX-sh nicht kennt). Eine Anmeldung ist nicht nötig; die Spezifikation ist öffentlich. Für die zweite Quelle die Basis-Adresse Ihrer Umgebung in SZENERA_API.
Ort
Kommandozeile

Am Ende liegt die Spezifikation des aktuellen Zugs datiert neben der Ihrer Umgebung, und Sie wissen, ob ein Pfad verschwunden ist, ein Pflichtfeld dazugekommen ist oder eine Antwort einen anderen Status trägt — bevor Ihre Integration es merkt.

Die Entwicklerseite liefert unter /api/openapi.json den Stand des aktuellen Zugs. Ihre Umgebung antwortet unter /v1/openapi.json mit dem, was dort tatsächlich läuft. Staging und Produktion können auseinanderliegen; erst der Vergleich sagt, welche Änderung Sie schon vor sich haben und welche noch kommt.

Schritte

Beide Spezifikationen laden

  1. Legen Sie die Spezifikation der Seite datiert ab:

    curl -sS https://developer.szenera.com/api/openapi.json -o "openapi-$(date +%F).json"

  2. Legen Sie die Spezifikation Ihrer Umgebung daneben:

    curl -sS "$SZENERA_API/v1/openapi.json" -o openapi-umgebung.json

  3. Notieren Sie, welche Fassung dort läuft:

    curl -sS "$SZENERA_API/health/version"

    { "service": "api", "version": "0.4.14", "builtAt": "2026-09-07T10:12:00+02:00", "environment": "production" }

Fassung und Pfade vergleichen

  1. Vergleichen Sie info.version beider Dateien:

    jq -r '.info.version' openapi-umgebung.json "openapi-$(date +%F).json"

    Gleiche Zahlen heißen nicht gleicher Inhalt: info.version ist eine Betreibereinstellung (Vorgabe 1.0.0) und bewegt sich nicht mit jedem Zug. Vergleichen Sie darum immer auch die Pfade.

  2. Vergleichen Sie Pfade und Methoden. Der Befehl listet jede Operation als METHODE /pfad; diff zeigt, was nur auf einer Seite steht:

    diff <(jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | "\(. | ascii_upcase) \($p)"' openapi-umgebung.json) \
     <(jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | "\(. | ascii_upcase) \($p)"' "openapi-$(date +%F).json")

Pflichtfelder, Antworten und Stabilität prüfen

  1. Prüfen Sie die Pflichtfelder der Schemata, die Sie senden. Die Liste steht in required:

    jq -c '.components.schemas.CreateSceneRequest.required' "openapi-$(date +%F).json"

    ["name"]

  2. Prüfen Sie die Antworten der Operationen, die Sie nutzen. Die Statuscodes stehen als Schlüssel unter responses; die Fehlercodes dazu nennt Das Fehlerformat:

    jq -c '.paths["/v1/scenes/{id}"].patch.responses | keys' "openapi-$(date +%F).json"

    ["200","401","403","404","409","422","429","502"]

  3. Prüfen Sie x-stability der Operationen, die Sie nutzen:

    jq -r '.paths["/v1/scenes/{id}"].patch["x-stability"]' "openapi-$(date +%F).json"

    Die Antwort lautet stable oder beta. Die Operation aus dem Beispiel ist stable.

Ergebnis prüfen

  • diff in Schritt 5 meldet keine Zeile mit < (nur in Ihrer Umgebung): Kein Pfad, den Sie aufrufen, ist entfernt oder umgezogen. Zeilen mit > sind neue Operationen und brechen nichts.
  • Die required-Listen der Schemata, die Sie senden, enthalten kein Feld, das Ihre Anfragen nicht mitschicken.
  • Die Statuscodes unter responses Ihrer Operationen sind unverändert, und keine trägt deprecated: true. Steht dort x-stability: beta, kann sich die Form noch bewegen — siehe Stabilitätsklassen und Auslauf.
  • Die datierte Datei bleibt liegen. Beim nächsten Zug laden Sie neu und vergleichen die beiden datierten Dateien miteinander.

Wenn etwas nicht klappt

Symptom Bedeutung Lösung
Ihre Umgebung liefert nach einem Zug noch den alten Stand Die Antwort von /v1/openapi.json darf fünf Minuten zwischengespeichert werden (Cache-Control: public, max-age=300). Nach fünf Minuten erneut laden.
info.version ist gleich, diff zeigt trotzdem Unterschiede Die Zahl in info.version folgt nicht dem Zug. Den Inhalt vergleichen, nicht die Zahl; die laufende Fassung nennt /health/version.
Eine Route fehlt in beiden Dateien, antwortet aber Sie ist als internal geführt und damit kein Teil der öffentlichen Fläche — in keiner der beiden Dateien. Nur öffentliche Operationen in die Integration nehmen; auf eine unbeschriebene Route gibt es keine Zusage.
Eine Operation trägt plötzlich deprecation-Kopfzeilen Sie läuft aus; x-sunset in der Beschreibung und Sunset in der Antwort nennen den Abschalt-Tag. Zwölf Monate bleiben — den Aufruf auf den genannten Nachfolger umstellen, siehe Stabilitätsklassen und Auslauf.
/health/version antwortet mit 429 Die Route ist auf 60 Aufrufe je Minute und Adresse begrenzt. Die in Retry-After genannten Sekunden warten.
/health/version meldet unknown oder eine Zahl mit -dev Die Umgebung läuft nicht aus einem Auslieferungs-Abbild. Für den Vergleich die Spezifikation nehmen, nicht die Fassung.

Weiterführendes