Zum Inhalt springen
Szenera DeveloperHandbuch
API › Referenz-Wegweiser › Einen eigenen Client aus der Spezifikation erzeugen
Kapitel

Einen eigenen Client aus der Spezifikation erzeugen

Es gibt heute keinen veröffentlichten Client: So erzeugen Sie aus openapi.json Ihren eigenen und bilden die Konventionen der API darin ab.

3 Minuten LesezeitAPIStand: 25.10.2026

Auf dieser Seite

Bevor Sie loslegen

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

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.

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:

    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.

  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.

  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.

  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.

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.

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