Zum Hauptinhalt springen
Version: 1.89.x (Q2 26)

Public API

Die Codesphere Public API ermöglicht die programmatische Steuerung deiner Workspaces, die Automatisierung von CI/CD-pipelines und die Integration von Codesphere-Ressourcen in bestehende interne Developer-Platforms.

Authentifizierung​

Alle API-Anfragen müssen mit einem API Key authentifiziert werden. Derzeit funktionieren diese Keys als Personal Access Tokens (PATs), das heißt sie übernehmen exakt dieselben Berechtigungen und Sichtbarkeiten wie das jeweilige Benutzerkonto.

Erstellen eines Tokens​

  1. Bei Codesphere anmelden.
  2. Auf das Avatar-Symbol oben rechts klicken.
  3. Im Dropdown-Menü User Settings auswählen.
  4. In der Seitenleiste zu API Keys navigieren.
  5. Auf Create New Key klicken und einen aussagekräftigen Namen vergeben (z. B. „GitHubActionsCI").

API Token Tabelle

Token speichern

Kopiere den Token sofort. Aus Sicherheitsgründen wird der Token-Wert nur einmal bei der Erstellung angezeigt. Falls er verloren geht, muss der alte Key widerrufen und ein neuer generiert werden.

Verwendung des Tokens​

Füge den API Key im Authorization-Header deiner HTTP-Anfragen mittels Bearer-Schema ein:

Authorization: Bearer <YOUR_API_TOKEN>

API-Dokumentation​

Die aktuellste Dokumentation für jeden verfügbaren Endpoint, einschließlich erforderlicher Parameter und Response-Schemas, ist direkt über unsere interaktive Swagger UI und Scalar UI verfügbar.

Interaktive Dokumentation

Die API-Dokumentation befindet sich unter [your_codesphere_url]/api/swagger-ui oder [your_codesphere_url]/api/scalar-ui

Endpoints können direkt innerhalb der Swagger UI getestet werden:

Public API Swagger UI Seite mit interaktiven API-Endpoints und Testfunktionen für Anfragen.

oder der Scalar UI:

Public API Scalar UI Seite mit Endpoint-Dokumentation und interaktiven Anfragebeispielen.

durch Angabe des API Keys.

Kernfunktionen​

Die API bietet vollständige CRUD-Kontrolle (Create, Read, Update, Delete) über deine Infrastruktur.

1. Workspace-Verwaltung​

Umgebungen programmatisch bereitstellen und verwalten.

  • Create: Neue Workspaces mit spezifischen Parametern initialisieren (Team ID, Plan ID, GitHub-URL, Branch, Replica-Anzahl).
  • Read: Status, Ressourcennutzung und Konfigurationsdetails abrufen.
  • Delete: Nicht genutzte Workspaces stilllegen, um Kosten zu verwalten.

2. Deployment-Steuerung​

Aktionen innerhalb deiner CI/CD-pipelines remote auslösen.

  • Git Pull: Einen Workspace zwingen, die neuesten Commits aus dem Remote-Repository zu ziehen (z. B. /workspaces/{workspaceId}/git/pull/{remote}).
  • Pipeline-Ausführung: Bestimmte Stufen der ci.yml auslösen (z. B. /pipeline/prepare/start für den Build oder /pipeline/run/start zum Starten der App).
  • Workloads stoppen: Laufende Anwendungen kontrolliert stoppen, bevor Updates angewendet werden.

3. Domain-Verwaltung​

Routing-Regeln programmatisch umschalten. Dies ist essenziell für Blue/Green- oder Zero-Downtime-Deployment-Strategien.

  • Update Connection: Eine Custom Domain sofort so umschalten, dass sie auf einen anderen Workspace verweist, über /domains/team/{teamId}/domain/{domainName}/workspace-connections.

Umgang mit asynchronen Operationen (Polling)​

Viele API-Aktionen, wie das Bauen eines Workspaces oder das Ausführen von Tests, sind asynchron. Die API bestätigt den Befehl sofort, doch die Aufgabe läuft im Hintergrund weiter.

Um dies zu handhaben, verwende ein Polling-Pattern:

  1. Aktion auslösen: Den Start-Endpoint aufrufen (z. B. POST /pipeline/prepare/start).
  2. Status abfragen: Den Status-Endpoint wiederholt in angemessenen Intervallen abfragen (z. B. GET /pipeline/prepare alle 5 Sekunden).
  3. Abschluss: Warten, bis der Endpoint den Status 200 OK zurückgibt, bevor mit dem nächsten Schritt fortgefahren wird.

Rate Limiting

Vermeide zu enge Schleifen (z. B. Anfragen alle 10 ms). Aggressives Polling kann Rate Limits auslösen. Für die meisten Build-Pipelines wird ein Intervall von 2–5 Sekunden empfohlen.