Public API Reference

Dieses Dokument beschreibt die REST-API-Endpunkte, die zur Verwaltung von Organizations und den zugehörigen Resource Groups und Mitgliedern zur Verfügung stehen.

Interaktive API-Dokumentation (Swagger UI)

Alle verfügbaren API-Endpunkte können direkt auf der eigenen Codesphere-Instanz interaktiv erkundet und getestet werden – über folgenden Pfad: https://[your_instance_URL]/api/swagger-ui/

Cluster-Administration

Die folgenden Endpunkte arbeiten auf Cluster-Ebene und sind für Plattformbetreiber gedacht. Im Gegensatz zu den weiter unten beschriebenen Organization-Endpunkten (die auf die Organizations beschränkt sind, denen man angehört), bieten diese einen clusterweiten Überblick und ermöglichen das Anlegen neuer Organizations und Administratoren.

Voraussetzungen

Um diese Endpunkte nutzen zu können, müssen folgende Voraussetzungen erfüllt sein:

• Flag cluster-admin aktiviert — Die Endpunkte sind hinter dem Flag cluster-admin abgesichert und werden nur registriert, wenn dieses aktiviert ist; andernfalls liefern Anfragen 404 Not Found. Die Cluster-Admin-Autorisierung basiert auf OpenFGA, daher muss zusätzlich das Preview-Flag openfga-authz aktiviert werden (ansonsten startet der Team-Service nicht). Beide Flags lassen sich in der config.yaml aktivieren:

  codesphere:
    experiments:
      - cluster-admin
    preview:
      openfga-authz: true

  Weitere Informationen zur Konfiguration von Flags finden sich unter Feature Flags.

• Cluster-Admin-Rechte — Der authentifizierte Benutzer muss ein Cluster-Admin sein; Anfragen anderer Benutzer werden mit dem Fehler NotAuthorized abgelehnt. Cluster-Admin wird man entweder durch Zuweisung während der Installation des Clusters oder durch Beförderung durch einen bestehenden Cluster-Admin über den Endpunkt Add Cluster Admin.

List All Organizations

Ruft alle Organizations im Cluster ab, beginnend mit der neuesten. Dies unterscheidet sich von List Organizations, das nur die Organizations zurückgibt, denen der authentifizierte Benutzer angehört.

• URL: GET /clusters/organizations
• Parameter: Keine.

Create Organization

Erstellt eine neue Organization zusammen mit ihrem initialen Administrator. Falls für die angegebene Admin-E-Mail-Adresse noch kein Codesphere-Konto existiert, wird für diese E-Mail-Adresse ein ausstehender (nicht registrierter) Benutzer angelegt. Sobald sich ein Benutzer mit dieser E-Mail-Adresse registriert, wird er automatisch zum Administrator der Organization.

• URL: POST /clusters/organizations
• Parameter:
  • Body:
    • name (String): Der Name der neuen Organization.
    • adminEmail (String): Die E-Mail-Adresse des Benutzers, der als initialer Administrator der Organization festgelegt werden soll.
• Fehler:
  • InvalidArgument - Wird zurückgegeben, wenn ein bestehendes Konto für adminEmail deaktiviert ist.

Add Cluster Admin

Gewährt einem Benutzer Cluster-Admin-Rechte. Falls für die angegebene E-Mail-Adresse noch kein Codesphere-Konto existiert, wird ein ausstehender (nicht registrierter) Benutzer angelegt.

• URL: POST /clusters/admins
• Parameter:
  • Body:
    • email (String): Die E-Mail-Adresse des Benutzers, dem Cluster-Admin-Rechte gewährt werden sollen.
• Fehler:
  • InvalidArgument - Wird zurückgegeben, wenn ein bestehendes Konto für email deaktiviert ist.

Organization-Verwaltung

List Organizations

Ruft eine Liste aller Organizations ab, denen der authentifizierte Benutzer angehört.

• URL: GET /organizations
• Parameter: Keine.

List Organization Resource Groups

Ruft alle Resource Groups ab, die offiziell einer bestimmten Organization zugeordnet sind.

• URL: GET /organizations/{organizationId}/resource-groups
• Parameter:
  • Path:
    • organizationId (UUID) - Die eindeutige ID der Organization.

Mitgliederverwaltung

List Organization Members

Ruft eine Liste aller Benutzer ab, die Teil der angegebenen Organization sind, einschließlich ihrer aktuellen Rollen und ihres Status.

• URL: GET /organizations/{organizationId}/members
• Parameter:
  • Path:
    • organizationId (UUID) - Die eindeutige ID der Organization.

Add Organization Member

Fügt einen bestehenden Benutzer einer Organization hinzu. Zu beachten ist, dass das Hinzufügen eines Benutzers zu einer Organization Voraussetzung dafür ist, dass er anschließend zu einer Resource Group innerhalb dieser Organization hinzugefügt werden kann.

• URL: POST /organizations/{organizationId}/members
• Parameter:
  • Path:
    • organizationId (UUID)
  • Body:
    • email (String): Die gültige E-Mail-Adresse des hinzuzufügenden Benutzers.
    • role (String): Die zuzuweisende Rolle ('admin' oder 'member').

Change Organization Role

Aktualisiert die organisatorische Rolle eines bestehenden Mitglieds (z. B. die Beförderung eines Mitglieds zum Administrator).

• URL: PUT /organizations/{organizationId}/members/{userId}/role
• Parameter:
  • Path:
    • organizationId (UUID)
    • userId (Number) - Die Benutzer-ID des Mitglieds.
  • Body:
    • role (String): Die neue Rolle ('admin' oder 'member').

Remove Organization Member

Entfernt einen Benutzer aus der Organization.

• URL: DELETE /organizations/{organizationId}/members/{userId}
• Parameter:
  • Path:
  • organizationId (UUID)
  • userId (Number) - Die Benutzer-ID des zu entfernenden Mitglieds.

Resource-Group-Integration

Create Resource Group

Erstellt eine neue kollaborative Resource Group. Je nach standalone-teams-Konfiguration der Umgebung müssen Resource Groups unter Umständen zwingend an eine Organization gebunden sein.

• URL: POST /resource-groups
• Parameter:
  • Body:
    • name (String): Der Name der neuen Resource Group.
    • dc (Integer): Die ID des Rechenzentrums, in dem die Resource Group gehostet wird.
    • organizationId (UUID, bedingt erforderlich): Die ID der Organization, zu der diese Resource Group gehört.
      • Hinweis: Ist das Feature-Flag standalone-teams auf der eigenen Instanz deaktiviert, ist dieser Parameter zwingend erforderlich, und der anfragende Benutzer muss Mitglied dieser Organization sein.

Migrate Resource Group to Organization

Migriert eine bestehende, eigenständige Resource Group in eine Organization oder eine Resource Group, die bereits Teil einer Organization ist, in eine andere Organization. Dies dient vor allem dazu, bestehende (Legacy-)Resource Groups in die neue einheitliche Governance-Struktur zu überführen.

• URL: POST /resource-groups/{resourceGroupId}/migrate
• Parameter:
  • Path:
    • resourceGroupId (Integer)
  • Body:
    • organizationId (UUID): Die Ziel-Organization.
    • force (Boolean, optional): Da eine Resource Group innerhalb einer Organization nur Mitglieder dieser Organization enthalten darf, kann die Migration einer Resource Group zu Konflikten führen, wenn einige Mitglieder der Resource Group nicht Mitglied der Ziel-Organization sind.
      • Bei force: true werden diese Nicht-Organization-Mitglieder während der Migration automatisch aus der Resource Group entfernt.
      • Bei force: false (oder wenn weggelassen) bricht die API die Migration ab und gibt einen Fehler (TeamMigrationFailed) zurück, falls Nicht-Mitglieder erkannt werden.