Es gibt viele Szenarien, in denen Sie Codesphere mit einem Drittsystem verbinden oder bestimmte Arbeitsabläufe im Zusammenhang mit Codesphere automatisieren möchten, um die Anforderungen Ihres Teams zu erfüllen.

Die derzeit verfügbaren Endpunkte in der aktuellsten Version finden Sie unter https://codesphere.com/api/swagger-ui oder wenn Ihr Unternehmen seine eigenen Codesphere-Installationen unter https://[Your_Base_URL]/api/swagger-ui betreibt.

Die Swagger-Benutzeroberfläche ist immer auf dem neuesten Stand und ermöglicht das Testen jedes Endpunkts direkt von der Benutzeroberfläche aus. Der Rest dieses Dokuments führt durch den Authentifizierungsprozess und zeigt einige Beispiele für die Verwendung der API.

Authentifizierung

Viele Endpunkte erfordern eine Authentifizierung über einen API-Schlüssel. Diese können Sie innerhalb von Codesphere über das Menü "Account Avatar" in der oberen rechten Ecke erstellen. Unter API-Schlüssel können Sie so viele Token erstellen, wie Sie benötigen. Achten Sie darauf, das Token nach der Erstellung zu kopieren - Sie können es später nicht mehr abrufen.

Dieses Token dient derzeit als persönliches Zugriffstoken, um die API zu ermächtigen, in Ihrem Namen zu handeln. Das bedeutet, dass es die gleiche Zugriffsebene wie Ihr Konto hat - es kann alle Ressourcen der Teams, denen Sie angehören, sehen und mit ihnen interagieren. In Zukunft werden wir feinkörnigere Token mit detaillierterer Kontrolle hinzufügen.

Sobald Sie Ihren API-Schlüssel bereit haben, können Sie mit den Endpunkten interagieren. Die Swagger-Benutzeroberfläche bietet auch eine Option zur Eingabe des API-Schlüssels als bearerAuth - Nach der Eingabe können Sie mit dem Testen der Endpunkte beginnen.

Beliebte API-Testtools wie Postman ermöglichen auch das Hinzufügen dieser Token für umfangreichere Tests.

Release Fluss

Während einzelne Endpunkte für sich genommen wertvoll sein können, ergibt sich der wahre Wert aus der Kombination mehrerer API-Aufrufe zu einem vollständigen User-Flow.

Das erste Beispiel, das wir uns ansehen wollen, ist die Erstellung eines Releases über ein Skript (d.h. Run on merge in einer GitHub-Action).

Einfacher Release-Koffer

1. Führen Sie einen Git Pull in Ihrem Workspace über die API durch /workspaces/{workspaceId}/git/pull/{remote} zum Beispiel: /workspaces/64286/git/pull/origin
2. (Optional) Bauen Sie Ihre Anwendung neu auf mit /workspaces/{workspaceId}/pipeline/prepare/start
3. Warten Sie auf das Ende der Prepare-Phase, d. h. auf die Abfrage /workspaces/{workspaceId}/pipeline/prepare bis er 200 zurückgibt
4. Stoppen Sie Ihre Anwendung, indem Sie zuerst die Run-Phase mit /workspaces/{workspaceId}/pipeline/run/stop
5. Starten Sie die Anwendung neu mit /workspaces/{workspaceId}/pipeline/run/start

Automatisierung von Zero Downtime Releases

Der einfache Fall eignet sich hervorragend für statische Websites und Anwendungen, die sofort neu gestartet werden können (d. h. wir verwenden ihn für unsere Website). Wenn Sie jedoch eine Anwendung automatisieren möchten Zero Downtime Release ist auch dies machbar. Führen Sie bei dem von Ihnen gewünschten Auslöser (d.h. einer Zusammenführung oder manuell) den folgenden Ablauf aus:

1. Erstellen Sie einen neuen Workspace mit dem gewünschten Git-Commit über /workspaces benötigen Sie die Team-ID, die Plan-ID, die Git-Url (+ Boolean, ob privat oder nicht), den Zweig und die Anzahl der Replicas.
2. Installieren und Erstellen aller erforderlichen Abhängigkeiten durch Ausführen der Prepare-Phase /workspaces/{workspaceId}/pipeline/prepare/start dd
3. Warten Sie auf das Ende der Prepare-Phase, d. h. auf die Abfrage /workspaces/{workspaceId}/pipeline/prepare bis er 200 zurückgibt
4. (Optional) Wenn Ihre ci.yml Unit-Tests o.ä. in der Testphase definiert, führen Sie diese aus und überprüfen Sie das Ergebnis mit /workspaces/{workspaceId}/pipeline/test/start
5. (Optional) Warten Sie, bis die Testphase beendet ist, d.h. rufen Sie /workspaces/{workspaceId}/pipeline/test bis er 200 zurückgibt - brechen Sie ab, wenn ein Test fehlschlägt.
6. Starten Sie die Anwendung mit /workspaces/{workspaceId}/pipeline/run/start
7. (Optional) Führen Sie Integrationstest-Pipelines gegen die neu erstellte Workspace-URL aus oder überprüfen Sie manuell, ob die neue Anwendung und der Git-Commit wie geplant funktionieren.
8. Wenn Sie erfolgreich sind, aktualisieren Sie den mit Ihrer produktiven Domäne verbundenen Workspace mit /domains/team/{teamId}/domain/{domainName}/workspace-connections - das aktuellste Schema, das für benötigt wird, ist in Swagger zu finden.