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 mit einem API-Key authentifiziert werden. Aktuell funktionieren diese Keys als Personal Access Tokens (PATs), das heißt, sie erben genau die gleichen Berechtigungen und Sichtbarkeiten wie das jeweilige Benutzerkonto.

Einen Token generieren​

  1. Bei Codesphere einloggen.
  2. Auf den 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 Table

Token sichern

Den Token sofort kopieren. Aus Sicherheitsgründen wird der Token-Wert nur einmal bei der Erstellung angezeigt. Bei Verlust muss der alte Key widerrufen und ein neuer generiert werden.

Verwendung 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 ist so konzipiert, dass volle CRUD-Kontrolle (Create, Read, Update, Delete) über die Infrastruktur besteht.

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: Ungenutzte 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 Stages 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.

Umgang mit asynchronen Operationen (Polling)​

Viele API-Aktionen, wie das Bauen eines Workspace oder das Ausführen von Tests, sind asynchron. Die API antwortet sofort, um den Befehl zu bestätigen, die eigentliche Aufgabe läuft jedoch im Hintergrund weiter.

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

  1. Aktion auslösen: Den Start-Endpunkt aufrufen (z. B. POST /pipeline/prepare/start).
  2. Status abfragen: Den Status-Endpunkt in sinnvollen Intervallen wiederholt abfragen (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). Zu aggressives Polling kann Rate Limits auslösen. Für die meisten Build-Pipelines wird ein Intervall von 2–5 Sekunden empfohlen.