Referenz zur öffentlichen API

Dieses Dokument beschreibt die REST-API-Endpunkte zur Verwaltung von Organizations sowie den zugehörigen Teams und Mitgliedern.

Cluster-Administration​

Die folgenden Endpunkte arbeiten auf Cluster-Ebene und sind für Plattformbetreiber gedacht. Im Gegensatz zu den unten beschriebenen Organisations-Endpunkten (die auf die Organizations beschränkt sind, denen man selbst angehört), bieten diese Endpunkte eine clusterweite Sicht und ermöglichen es, neue Organizations und Administratoren anzulegen.

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, in denen der authentifizierte Nutzer Mitglied ist.

• 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 ein ausstehender (nicht registrierter) Nutzer für diese E-Mail-Adresse angelegt. Sobald sich ein Nutzer mit dieser E-Mail-Adresse registriert, wird er automatisch Administrator der Organization.

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

Add Cluster Admin​

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

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

Organisationsverwaltung​

List Organizations​

Ruft eine Liste aller Organizations ab, in denen der authentifizierte Nutzer Mitglied ist.

• URL: GET /organizations
• Parameter: Keine.

List Organization Teams​

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

• URL: GET /organizations/{organizationId}/teams
• Parameter:
  • Pfad:
    • organizationId (UUID) - Die eindeutige Kennung der Organization.

Mitgliederverwaltung​

List Organization Members​

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

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

Add Organization Member​

Fügt einen bestehenden Nutzer zu einer Organization hinzu. Zu beachten ist, dass das Hinzufügen eines Nutzers zu einer Organization Voraussetzung dafür ist, dass er einem Team innerhalb dieser Organization hinzugefügt werden kann.

• URL: POST /organizations/{organizationId}/members
• Parameter:
  • Pfad:
    • organizationId (UUID)
  • Body:
    • email (String): Die gültige E-Mail-Adresse des hinzuzufügenden Nutzers.
    • 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:
  • Pfad:
    • organizationId (UUID)
    • userId (Number) - Die userId des Mitglieds.
  • Body:
    • role (String): Die neue Rolle ('admin' oder 'member').

Remove Organization Member​

Entfernt einen Nutzer aus der Organization.

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

Team-Integration​

Create Team​

Erstellt ein neues Team für die Zusammenarbeit. Abhängig von der standalone-teams-Konfiguration der Umgebung müssen Teams unter Umständen zwingend an eine Organization gebunden sein.

• URL: POST /teams
• Parameter:
  • Body:
    • name (String): Der Name des neuen Teams.
    • dc (Integer): Die ID des Rechenzentrums, in dem das Team gehostet wird.
    • organizationId (UUID, bedingt erforderlich): Die ID der Organization, zu der dieses Team gehört.
      • Hinweis: Wenn das Feature-Flag standalone-teams auf der Instanz deaktiviert ist, ist dieser Parameter zwingend erforderlich, und der anfragende Nutzer muss Mitglied dieser Organization sein.

Migrate Team to Organization​

Migriert ein bestehendes, eigenständiges Team in eine Organization oder ein Team, das bereits einer Organization angehört, in eine andere Organization. Dies wird vor allem genutzt, um bestehende ältere Teams unter der neuen einheitlichen Governance-Struktur zusammenzuführen.

• URL: POST /teams/{teamId}/migrate
• Parameter:
  • Pfad:
    • teamId (Integer)
  • Body:
    • organizationId (UUID): Die Ziel-Organization.
    • force (Boolean, optional): Da ein Team innerhalb einer Organization nur Mitglieder dieser Organization enthalten darf, kann die Migration eines Teams zu Konflikten führen, falls einige Teammitglieder nicht Teil der Ziel-Organization sind.
      • Bei force: true werden diese Nicht-Organization-Nutzer während der Migration automatisch aus dem Team entfernt.
      • Bei force: false (oder wenn nicht angegeben) bricht die API die Migration ab und gibt einen Fehler (TeamMigrationFailed) zurück, falls Nicht-Mitglieder erkannt werden.