Zum Hauptinhalt springen
Version: Weekly Build

Public API

Die Public API von Codesphere 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. Aktuell funktionieren diese Keys als Personal Access Tokens (PATs), das heißt, sie erben exakt dieselben Berechtigungen und Sichtbarkeiten wie das jeweilige Benutzerkonto.

Einen 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

Den 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.

Verwendung des Tokens​

Den API Key im Authorization-Header der HTTP-Anfragen über das 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 unsere interaktive Swagger UI und Scalar UI verfügbar.

Interaktive Dokumentation

Die API-Dokumentation ist zu finden 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 in der Scalar UI:

Public API Scalar UI-Seite mit Endpunkt-Dokumentation und interaktiven Beispielanfragen.

indem der API Key angegeben wird.

Kernfunktionen​

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

1. Workspace-Verwaltung​

Umgebungen programmatisch bereitstellen und verwalten.

  • Create: Neue Workspaces mit spezifischen Parametern initialisieren (Resource Group ID, Plan ID, GitHub-URL, Git Ref, Replica-Anzahl). 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 steuern 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 sie weggelassen, gilt jeweils das Standardverhalten des Workspace-Service.
  • 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 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 Anwendung).
  • Workloads stoppen: Laufende Anwendungen kontrolliert stoppen, bevor Updates angewendet werden.

3. Static Builds​

Eine Landscape als vorgefertigte Images exportieren und das Ergebnis weiterverwenden.

  • Export: POST /static-builds baut ein CI-Profil eines Workspace oder eines Git-Repositorys in Images und pusht diese in eine Registry. GET /static-builds/{conversionId}/events liefert den Fortschritt und das Ergebnis als Stream.
  • Nutzen: staticBuildArtifact an POST /workspaces übergeben, um einen Workspace aus einem Artefakt zu erstellen. Siehe Static Builds.

4. Domain-Verwaltung​

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

  • Update Connection: Eine benutzerdefinierte Domain sofort auf einen anderen Workspace umleiten, über /domains/resource-group/{resourceGroupId}/domain/{domainName}/workspace-connections.

5. 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 — andernfalls schlägt die Workspace-Erstellung fehl.

Umgang mit asynchronen Vorgängen (Polling)​

Viele API-Aktionen, etwa 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, ein Polling-Pattern 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 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.