Zum Hauptinhalt springen
Version: Weekly Build

Public API

Die Codesphere Public API ermöglicht es, Workspaces programmatisch zu steuern, CI/CD-Pipelines zu automatisieren und Codesphere-Ressourcen in bestehende interne Developer Platforms zu integrieren.

Authentifizierung​

Alle API-Anfragen müssen mit einem API-Schlüssel authentifiziert werden. Aktuell fungieren diese Schlüssel als Personal Access Tokens (PATs), das heißt, sie erben genau dieselben Berechtigungen und Sichtbarkeiten wie das jeweilige Benutzerkonto.

Token erstellen​

  1. Bei Codesphere anmelden.
  2. Auf das Avatar 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

Das Token sofort kopieren. Aus Sicherheitsgründen wird der Token-Wert nur einmal bei der Erstellung angezeigt. Geht er verloren, muss der alte Schlüssel widerrufen und ein neuer erstellt werden.

Verwendung des Tokens​

Den API-Schlüssel im Authorization-Header der HTTP-Anfragen mit dem Bearer-Schema einbinden:

Authorization: Bearer <YOUR_API_TOKEN>

API-Dokumentation​

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

Interaktive Dokumentation

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

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

Public API Swagger UI-Seite mit interaktiven API-Endpunkten und Steuerelementen zum Testen von Anfragen.

oder der Scalar UI:

Public API Scalar UI-Seite mit Endpunktdokumentation und interaktiven Anfragebeispielen.

durch Angabe des API-Schlüssels.

Kernfunktionen​

Die API ist darauf ausgelegt, vollständige CRUD-Kontrolle (Create, Read, Update, Delete) über die Infrastruktur zu ermöglichen.

1. Workspace-Verwaltung​

Umgebungen programmatisch bereitstellen und verwalten.

  • Create: Neue Workspaces mit spezifischen Parametern initialisieren (Team ID, Plan ID, GitHub-URL, Git Ref, Replica-Anzahl). Mit dem Feld gitRef kann ein Workspace bereits bei der Erstellung auf einen bestimmten Branch, Tag oder Commit SHA festgelegt werden.
  • Read: Status, Ressourcennutzung und Konfigurationsdetails abrufen.
  • Delete: Nicht genutzte Workspaces stilllegen, um Kosten zu kontrollieren.

2. Deployment-Steuerung​

Aktionen innerhalb der CI/CD-Pipelines remote auslösen.

  • Git Pull: Einen Workspace dazu zwingen, die neuesten Commits vom 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 zum Bauen 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.

  • Verbindung aktualisieren: Eine benutzerdefinierte Domain sofort so umschalten, dass sie auf einen anderen Workspace zeigt, über /domains/team/{teamId}/domain/{domainName}/workspace-connections.

Umgang mit asynchronen Vorgängen (Polling)​

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

Um dies zu handhaben, ein Polling-Muster verwenden:

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

Rate Limiting

Enge Abfrageschleifen vermeiden (z. B. Anfragen alle 10 ms). Zu aggressives Polling kann Rate Limits auslösen. Für die meisten Build-Pipelines wird ein Intervall von 2–5 Sekunden empfohlen.