# Die Spezifikation gegen Ihren Stand vergleichen

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.

> **Typ:** anleitung
> **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

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:

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

2. Legen Sie die Spezifikation Ihrer Umgebung daneben:

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

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

   ```bash
   curl -sS "$SZENERA_API/health/version"
   ```

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

### Fassung und Pfade vergleichen

4. Vergleichen Sie `info.version` beider Dateien:

   ```bash
   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.

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

   ```bash
   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

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

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

   ```json
   ["name"]
   ```

7. Prüfen Sie die Antworten der Operationen, die Sie nutzen. Die Statuscodes stehen als Schlüssel unter `responses`; die Fehlercodes dazu nennt [Das Fehlerformat](/de/api/error-format):

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

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

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

   ```bash
   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](/de/changes/stability-and-sunset).
- 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](/de/changes/stability-and-sunset). |
| `/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

- [Release-Züge, Notizen und Abkündigungen](/de/changes/release-notes)
- [Die Referenz lesen](/de/api/read-reference)
- [Einen eigenen Client aus der Spezifikation erzeugen](/de/api/generate-client)