# Einen eigenen Client aus der Spezifikation erzeugen

Es gibt heute keinen veröffentlichten Client für die Szenera-API. Nach dieser Anleitung erzeugen Sie aus `openapi.json` Ihren eigenen und bilden die Konventionen der API darin ab: Ausweis, Fehler, Versionsprüfung, Idempotenz und Blättern.

> **Typ:** anleitung
> **Für wen:** Wer die API aus einer Programmiersprache heraus anspricht und nicht jeden Aufruf von Hand schreiben will.
> **Voraussetzung:** ein Generator für OpenAPI 3.1 in Ihrer Sprache und ein Schlüssel `ak_…`
> **Ort:** Kommandozeile

## Der ehrliche Stand

Die Plattform hat einen TypeScript-Client, aber er ist Teil der Portale und wird nicht veröffentlicht; die Entwicklerseite verspricht keinen. Was es gibt, ist die Spezifikation — vollständig, mit Beispiel je Schema, im Format OpenAPI 3.1.0. Daraus erzeugt jeder gängige Generator einen Client.

## Schritte

1. Laden Sie die Spezifikation:

   ```bash
   curl -sS -o openapi.json "https://developer.szenera.com/api/openapi.json"
   ```

   Oder von Ihrer Umgebung, wenn deren Stand vom Release abweicht: `curl -sS -o openapi.json "$SZENERA_API/v1/openapi.json"`.

2. Erzeugen Sie den Client mit einem Generator Ihrer Wahl. Prüfen Sie vorher, dass er OpenAPI **3.1** versteht — die Spezifikation nutzt Typen wie `["string", "null"]`, die ein 3.0-Generator nicht kennt. Die 19 Tags der Spezifikation eignen sich als Modulgrenzen.

3. Setzen Sie den Ausweis zentral: `Authorization: Bearer ak_…` an jedem Aufruf, aus einer Umgebungsvariablen, nie aus dem Quelltext. Ein Schlüssel läuft nicht nach 15 Minuten ab — Ihr Client braucht keine Auffrischung.

4. Bilden Sie Fehler auf `code` ab. Jeder Fehler hat die Form `Bereich.Ursache`; leiten Sie je Namensraum einen typisierten Fehler ab (`Auth.*`, `Permission.*`, `Validation.*`, `Conflict.*`, `RateLimit.*`, `*.NotFound`, `Integration.*`) und tragen Sie `traceId` in jeden davon. Schalten Sie nie auf `message`. Das Format steht unter [Das Fehlerformat](/de/api/error-format).

5. Bilden Sie die Versionsprüfung ab: Lesen Sie bei Szenen, Playlisten, Programmen, Rollen und Displays das Feld `version` und senden Sie es bei jeder Änderung als `If-Match`. Bei `409 Conflict.OptimisticLock` liest Ihr Client neu und wiederholt einmal — siehe [Gleichzeitige Änderungen](/de/api/etag-and-if-match).

6. Geben Sie jedem verändernden Aufruf einen `Idempotency-Key` — selbst gewählt, mindestens 8 Zeichen, je Vorgang neu. Eine Wiederholung mit demselben Schlüssel liefert die gespeicherte Antwort mit `Idempotent-Replay: true`; derselbe Schlüssel mit anderem Rumpf antwortet `422 Validation.IdempotencyKeyReused`. Details unter [Idempotenz von Anfang an](/de/getting-started/idempotency).

7. Bauen Sie eine Cursor-Schleife für Listen: `limit` und `cursor` senden, `items` einsammeln, mit `nextCursor` fortsetzen, bis es fehlt. Die vier Routen mit `page` behandeln Sie getrennt — siehe [Blättern](/de/api/pagination).

## Ergebnis prüfen

- Die Beispiele der Schemata sind Ihre ersten Testdaten: alle 741 Schemata der ausgelieferten Spezifikation tragen eines, und sie passen zusammen (dieselben Kennungen, dieselbe Organisation).
- Ein erster lesender Aufruf — `GET /v1/me` — antwortet `200` mit `tenantId` Ihrer Organisation.
- Ein Aufruf mit falschem Schlüssel landet in Ihrem typisierten `Auth`-Fehler mit `code: Auth.ApiKeyUnknown`.
- Jede Operation, die Ihr Client anbietet, trägt in der Spezifikation `x-stability: stable` oder `beta` (bei `beta` kann sich die Form noch bewegen); eine spätere Fassung der Spezifikation vergleichen Sie mit [Die Spezifikation gegen Ihren Stand vergleichen](/de/changes/compare-specification).

## Wenn etwas nicht klappt

| Symptom | Bedeutung | Lösung |
|---|---|---|
| Der Generator bricht mit einem Formatfehler ab | Er kennt OpenAPI 3.1 nicht. | Einen Generator mit 3.1-Unterstützung wählen. |
| `422 Validation.Failed` mit `details.issues` | Der Rumpf verletzt das Schema; `issues` nennt den Feldpfad. | Das Beispiel des Anfrageschemas mit Ihrem Rumpf vergleichen. |
| `403 Permission.Denied` bei einer Route, die der Client anbietet | Der Generator erzeugt jede Operation — auch die, die ein Schlüssel nicht darf. | Das Recht in der Referenz prüfen; nicht schlüsselfähige Rechte bleiben Sitzungen vorbehalten — siehe [Anmeldung](/de/api/authentication). |
| Ein Feld fehlt in der Antwort, das der Client verlangt | Ihre Umgebung läuft auf einem anderen Stand als die Spezifikation, aus der Sie erzeugt haben. | Die Spezifikation der Umgebung laden (`GET /v1/openapi.json`) und neu erzeugen. |

## Weiterführendes

- [Die Referenz lesen](/de/api/read-reference)
- [Das Fehlerformat](/de/api/error-format)
- [Die Spezifikation gegen Ihren Stand vergleichen](/de/changes/compare-specification)