Die API nutzen

Alles, was die Konsole tut, tut sie über dieselbe REST-API – Cluster erstellen, Node-Pools verwalten, kubeconfigs ausstellen, die Abrechnung lesen. Diese Seite ist die Orientierung: die Form der API und die Konventionen, die über alle Endpunkte hinweg gelten. Die API-Referenz (derzeit auf Englisch) dokumentiert dann jeden Endpunkt vollständig, generiert aus dem Live-Schema.

Basis-URL und Versionierung

Die API liegt unter dem Konsolen-Host, und die stabile Oberfläche ist mit dem Präfix /v1/ versioniert:

https://console.paasbox.com/api/v1/

Anfragen und Antworten sind JSON über HTTPS. Eine neue Hauptversion würde zu /v2/ wechseln, statt /v1/ unter dir zu verändern.

Authentifizierung

Zwei Wege hinein, je nachdem, wer aufruft:

Sitzung – die Konsole authentifiziert dich über eine Browser-Sitzung. Das ist der interaktive Weg; du musst nichts Besonderes tun.
API-Key – für Skripte, CI und alles Nicht-Interaktive. Erstelle in der Konsole einen Key (siehe Teams & API-Keys) und sende ihn im Authorization-Header.

Keys sehen aus wie pbx_live_…, werden bei der Erstellung einmalig angezeigt, gehören einem Team-Mitglied und lassen sich jederzeit widerrufen. Sende ihn bei jeder Anfrage mit:

curl -s -H "Authorization: Token $PAASBOX_API_KEY" \
  https://console.paasbox.com/api/v1/teams/<team>/clusters/

Behalte den Key als das dauerhafte Geheimnis und nutze ihn, um pro Lauf eine frische kubeconfig zu holen, statt langlebige Cluster-Zugangsdaten zu speichern.

Alles hat einen Team-Scope

Ressourcen gehören einem Team, nicht einer Person – deshalb tragen die Pfade, die Ressourcen besitzen, den Team-Slug:

/api/v1/teams/{team_slug}/clusters/
/api/v1/teams/{team_slug}/clusters/{cluster}/node-pools/

Dein Key handelt in den Teams, in denen sein Besitzer Mitglied ist. Die Seite Teams & API-Keys behandelt Rollen und was ein Key darf; das Aktivitätsprotokoll führt jede per Key ausgelöste Änderung auf eine Person zurück.

Pagination

Listen-Endpunkte sind zu je 100 Einträgen paginiert. Fordere eine Seite mit ?page= an:

curl -s -H "Authorization: Token $PAASBOX_API_KEY" \
  "https://console.paasbox.com/api/v1/teams/<team>/clusters/?page=2"

Die Antwort verpackt die Einträge in eine kleine Hülle – count ist die Gesamtzahl, next und previous sind Seiten-URLs (oder null an den Enden), und results enthält die Einträge:

{
  "count": 137,
  "next": "https://console.paasbox.com/api/v1/teams/acme/clusters/?page=3",
  "previous": "https://console.paasbox.com/api/v1/teams/acme/clusters/?page=1",
  "results": [ /* … */ ]
}

Statuscodes und Fehler

Es gelten die üblichen HTTP-Semantiken. Die, die man kennen sollte:

Code	Bedeutung
`200` / `201` / `204`	Erfolg – gelesen, erstellt oder gelöscht (ohne Body).
`202`	Angenommen – die Arbeit läuft asynchron (z. B. ein startender Cluster); frag die Ressource für den Status ab.
`401` / `403`	Nicht authentifiziert / nicht erlaubt – prüfe den Key und die Rolle des Aufrufers im Team.
`402`	Ein Abrechnungs- oder Ausgabenlimit blockiert die Aktion – kläre es in der Konsole und versuche es erneut.
`404`	Keine solche Ressource, oder sie liegt außerhalb der Teams, die dein Key erreicht.
`409`	Konflikt mit dem aktuellen Zustand (z. B. ein Name ist bereits vergeben).
`412` / `422`	Die Anfrage wurde verstanden, aber abgelehnt – eine Vorbedingung schlug fehl, oder ein Feld war ungültig.

Fehlerantworten tragen einen JSON-Body, der beschreibt, was schiefging; behandle den Statuscode als maßgeblich dafür, wie zu reagieren ist.

Die vollständige Referenz

Die API-Referenz listet jeden Endpunkt, Parameter, Request-Body und jede Antwortform auf. Sie wird aus dem Schema des laufenden Dienstes generiert und folgt so der API, wie sie ausgeliefert wird.