API SDK Client generieren

• Was ist OpenAPI?
• Voraussetzungen
• sdk.sh erstellen
• PHP — Beispiel: WordPress oder bestehende PHP-App
• JavaScript — Beispiel: Node.js / Next.js
• TypeScript — Beispiel: Next.js / Astro
• Workflow nach API-Änderungen
• Nächste Schritte

Dieser Guide erklärt, wie du aus der Flyo API SDK Integration einen vollständig typisierten Client für dein bestehendes Projekt generierst — egal ob WordPress, Laravel, Next.js, Astro oder eine andere Plattform.

---

Was ist OpenAPI?

OpenAPI (früher «Swagger») ist ein offener Standard zur maschinenlesbaren Beschreibung von REST-APIs. Eine OpenAPI-Datei (JSON oder YAML) enthält alle Endpunkte, Parameter, Request- und Response-Strukturen einer API.

Der grosse Vorteil: mit einem OpenAPI Generator lässt sich aus dieser Beschreibung automatisch ein vollständig typisierter Client in nahezu jeder Programmiersprache generieren — ohne manuelles Schreiben von HTTP-Requests oder Response-Parsing.

Flyo stellt für jede konfigurierte API SDK Integration eine fertige OpenAPI-Datei bereit. Du generierst daraus einen Client, der exakt zu deinen konfigurierten Entitäten und Content Pools passt.

Ausgangslage

Du hast bereits ein bestehendes Projekt (z.B. ein WordPress-Plugin, eine Laravel-App, ein Next.js-Projekt). Das SDK wird als Unterordner (sdk/) in dieses Projekt hinein generiert und manuell eingebunden — es entsteht kein separates SDK-Repository.

---

Voraussetzungen

1. Bestehende Flyo API SDK Integration — konfiguriert mit den gewünschten Content Pools. Noch keine Integration? → API SDK Integration einrichten
2. OpenAPI Generator CLI global installiert:

npm install @openapitools/openapi-generator-cli -g

Alternativ per Docker oder JAR-Datei: openapi-generator.tech/docs/installation

3. OpenAPI-URL deiner Integration — diese findest du in der Flyo-Oberfläche unter deiner API SDK Integration. Sie hat das Format:

https://api.flyo.cloud/integration/sdk/<id>/<token>

---

sdk.sh erstellen

Wir empfehlen, den Generator-Befehl in einem Shell-Script sdk.sh im Projekt-Root zu speichern. So lässt sich der Client jederzeit mit einem einzigen Befehl reproduzierbar neu generieren — besonders wichtig, wenn sich die API in Flyo ändert.

Erstelle die Datei sdk.sh im Projekt-Root:

#!/bin/sh
openapi-generator-cli generate \
  -i https://api.flyo.cloud/integration/sdk/<id>/<token> \
  -g <generator> \
  -o sdk \
  --global-property=apis,models

Mach das Script ausführbar:

chmod +x sdk.sh

Das Flag --global-property=apis,models ist wichtig: es generiert nur die API-Klassen und Models — ohne automatisch erzeugte Dokumentation, Tests und überflüssige Konfigurationsdateien. Das hält den generierten Code schlank und übersichtlich.

sdk/ committen

Committe den generierten sdk/-Ordner in dein Repository. So siehst du bei jedem git diff genau, was sich an der API geändert hat — sehr nützlich für Code-Reviews und um Breaking Changes frühzeitig zu erkennen.

Sowohl sdk.sh als auch sdk/ werden ins Repository eingecheckt. Nach API-Änderungen in Flyo: ./sdk.sh ausführen und den Diff reviewen.

---

PHP — Beispiel: WordPress oder bestehende PHP-App

Passe sdk.sh für PHP an:

#!/bin/sh
openapi-generator-cli generate \
  -i https://api.flyo.cloud/integration/sdk/<id>/<token> \
  -g php \
  -o sdk \
  --global-property=apis,models

Der Generator erzeugt den Client unter sdk/lib/. Da du bereits ein bestehendes Projekt hast (und keine neue Composer-Abhängigkeit installierst), musst du den PSR-4-Autoload-Eintrag manuell in deine eigene composer.json einfügen:

{
  "autoload": {
    "psr-4": {
      "OpenAPI\\Client\\": "sdk/lib/"
    }
  }
}

Anschliessend den Autoloader neu generieren:

composer dump-autoload

Jetzt kannst du die generierten API-Klassen direkt in deinem Projekt verwenden:

use OpenAPI\Client\Api\BlogsApi;
use OpenAPI\Client\Configuration;

$config = Configuration::getDefaultConfiguration()
    ->setAccessToken('dein-bearer-token');

$api = new BlogsApi(new GuzzleHttp\Client(), $config);
$result = $api->getBlogsPool();

WordPress

In einem WordPress-Plugin fügst du die composer.json in deinen Plugin-Ordner ein und rufst composer dump-autoload dort aus. Der erzeugte vendor/autoload.php wird dann am Anfang deiner Plugin-Hauptdatei eingebunden.

---

JavaScript — Beispiel: Node.js / Next.js

Passe sdk.sh für JavaScript an:

#!/bin/sh
openapi-generator-cli generate \
  -i https://api.flyo.cloud/integration/sdk/<id>/<token> \
  -g javascript \
  -o sdk \
  --global-property=apis,models,apiTests=false,modelTests=false,apiDocs=false,modelDocs=false,supportingFiles \
  --additional-properties=usePromises=true

Der Generator erzeugt den Client unter sdk/src/. Da du bereits ein bestehendes Projekt hast, ignorierst du die generierte sdk/package.json — du installierst das SDK nicht als separates NPM-Paket. Stattdessen importierst du direkt aus dem Unterordner:

import { BlogsApi, ApiClient } from './sdk/src/index.js'

const client = new ApiClient()
client.authentications['bearerAuth'].accessToken = 'dein-token'

const api = new BlogsApi(client)
const result = await api.getBlogsPool()

Filter in JavaScript/TypeScript

Der OpenAPI Generator hat Probleme mit der Serialisierung von verschachtelten Filterobjekten. Installiere qs und überschreibe die Serialisierung:

npm install qs

import { stringify } from 'qs'
import { Configuration } from './sdk/src/index.js'

const config = new Configuration({
  queryParamsStringify: (params) => stringify(params)
})

Mehr zu Filtern: API SDK — Filter-Parameter

---

TypeScript — Beispiel: Next.js / Astro

Passe sdk.sh für TypeScript an (hier mit dem typescript-fetch-Generator, der ohne zusätzliche HTTP-Library auskommt):

#!/bin/sh
openapi-generator-cli generate \
  -i https://api.flyo.cloud/integration/sdk/<id>/<token> \
  -g typescript-fetch \
  -o sdk \
  --global-property=apis,models

Import direkt in deinem Projekt:

import { BlogsApi, Configuration } from './sdk'

const config = new Configuration({
  accessToken: 'dein-token'
})

const api = new BlogsApi(config)
const result = await api.getBlogsPool()

Für Projekte mit Axios (z.B. Nuxt): verwende stattdessen -g typescript-axios.

---

Workflow nach API-Änderungen

Wenn du in Flyo die API SDK Integration anpasst (neue Felder, neue Entitäten), ist folgendes zu tun:

# Client neu generieren
./sdk.sh

# Änderungen reviewen
git diff sdk/

# Änderungen committen
git add sdk/
git commit -m "chore: update sdk"

Der Diff zeigt dir genau, welche Klassen und Properties sich geändert haben — ideal, um Breaking Changes zu erkennen, bevor sie in Produktion gehen.

---

Nächste Schritte

Der generierte Client deckt alle Basis-Operationen ab. Für fortgeschrittene Nutzung:

Thema	Beschreibung	Dokumentation
Filter	WHERE-Konditionen direkt in der Abfrage	Filter-Parameter
Paginierung	Seitenweise Abfrage grosser Datensätze	Paginierung
Felder limitieren	Nur benötigte Felder abrufen	Felder limitieren
Sortierung	Ausgabe sortieren	Felder sortieren
Öffentliche vs. private SDKs	Caching, reCAPTCHA, Bearer-Token	Authentifizierung
POST / PUT	Inhalte erstellen und ändern via API	Öffentliche Schnittstelle