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-Plattformen zu integrieren.

Authentifizierung​

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

Erstellen eines Tokens​

  1. Bei Codesphere anmelden.
  2. Auf den Avatar in der oberen rechten Ecke 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 Table

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 Key widerrufen und ein neuer generiert werden.

Verwenden des Tokens​

Den API-Key im Authorization-Header der HTTP-Anfragen mit dem Bearer-Schema angeben:

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

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

Public API Swagger UI page showing interactive API endpoints and request testing controls.

oder der Scalar UI:

Public API Scalar UI page showing endpoint documentation and interactive request examples.

indem der API-Key angegeben wird.

Kernfunktionen​

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

1. Workspace-Verwaltung​

Umgebungen programmatisch bereitstellen und verwalten.

  • Create: Neue Workspaces mit spezifischen Parametern initialisieren (Team ID, Plan ID, GitHub-URL, Git Ref, Anzahl der Replicas). Mit dem Feld gitRef lässt sich ein Workspace bereits bei der Erstellung an einen bestimmten Branch, Tag oder Commit-SHA binden. Zwei optionale boolesche Felder ermöglichen die Kontrolle über das Git-Clone-Verhalten: skipLfs auf true setzen, um das Herunterladen von Git-LFS-Objekten beim Klonen zu überspringen, und recurseSubmodules auf false setzen, um das rekursive Klonen von Submodulen zu überspringen. Werden beide Felder weggelassen, gilt das Standardverhalten des Workspace-Service.
  • Read: Status, Ressourcennutzung und Konfigurationsdetails abrufen.
  • Delete: Nicht genutzte Workspaces stilllegen, um Kosten zu steuern.

2. Deployment-Steuerung​

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

  • Git Pull: Einen Workspace dazu 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 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 Custom Domain sofort so umleiten, dass sie auf einen anderen Workspace zeigt, über /domains/team/{teamId}/domain/{domainName}/workspace-connections.

4. Metadaten & Discovery​

Plattformfähigkeiten abfragen, bevor Ressourcen bereitgestellt werden.

  • Unterstützte Git-Provider: GET /metadata/git-providers liefert die Git-Provider, von denen Codesphere klonen kann. Jeder Eintrag enthält eine url (die Basis-URL des Providers) und eine kind (z. B. GitHub, GitLab, Bitbucket). Diesen Endpunkt vor dem Erstellen eines Workspace aufrufen, um zu bestätigen, dass der Host des Ziel-Repositorys unterstützt wird — die Workspace-Erstellung schlägt andernfalls fehl.

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, die eigentliche Aufgabe läuft jedoch im Hintergrund weiter.

Um dies zu handhaben, wird ein Polling-Muster verwendet:

  1. Aktion auslösen: Den Start-Endpunkt aufrufen (z. B. POST /pipeline/prepare/start).
  2. Status abfragen: Den Status-Endpunkt wiederholt in angemessenen Intervallen 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 Schleifen vermeiden (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.