API-Referenz
Canopy stellt eine vollständige REST-API bereit, die alles ermöglicht, was Sie auch in der Web-Benutzeroberfläche tun können. Sie können sie verwenden, um Inventar-Updates zu automatisieren, in CI/CD-Pipelines zu integrieren, benutzerdefinierte Dashboards zu erstellen oder EA-Daten in andere Werkzeuge einzubinden (BI, GRC, ITSM, Tabellenkalkulationen).
Die vollständige OpenAPI-3.1-Spezifikation ist im Abschnitt API-Endpunkte der Seitenleiste verfügbar — jeder Endpunkt, Parameter und jede Antwortstruktur, bei jedem Release aus dem Backend-Quellcode neu generiert.
Basis-URL
Alle API-Endpunkte befinden sich unter dem Präfix /api/v1. Ihre Canopy-Umgebungs-URL folgt dem Schema:
https://{ihr-slug}-canopy.rhizo-tech.org/api/v1
Ersetzen Sie {ihr-slug} durch den Slug Ihrer Organisation, der in Ihrem Rhizo-Konto und in der URL, über die Sie auf Canopy zugreifen, angezeigt wird.
Die einzige Ausnahme ist der Health-Endpunkt, der unter /api/health (ohne Versionspräfix) eingehängt ist.
Interaktive API-Referenz
Die vollständige OpenAPI-3.1-Spezifikation ist im Abschnitt API-Endpunkte der Seitenleiste verfügbar. Jede Endpunktseite enthält ein interaktives Playground, in dem Sie Ihren Bearer-Token eingeben und Live-Anfragen gegen Ihre Canopy-Umgebung ausführen können.
Die rohe Spezifikation ist auch für Code-Generatoren herunterladbar:
https://docs.rhizo-tech.org/api/openapi.json
Um den interaktiven Playground zu nutzen, öffnen Sie eine beliebige Endpunktseite im Abschnitt API-Endpunkte der Seitenleiste, geben Sie Ihren Bearer-Token im Feld Authorization ein, füllen Sie die Parameter aus und klicken Sie auf Send.
Authentifizierung
Alle Endpunkte außer /auth/*, dem Health-Check und öffentlichen Web-Portalen erfordern ein JSON Web Token im Authorization-Header:
Authorization: Bearer <access_token>
Token anfordern
POST /api/v1/auth/login mit Ihrer E-Mail-Adresse und Ihrem Passwort:
curl -X POST https://{ihr-slug}-canopy.rhizo-tech.org/api/v1/auth/login \
-H "Content-Type: application/json" \
Die Antwort enthält ein access_token:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer"
}
Token sind 24 Stunden gültig. Verwenden Sie POST /api/v1/auth/refresh, um eine Sitzung ohne erneute Anmeldedaten zu verlängern.
Wenn Ihre Organisation Single Sign-On verwendet, können Sie sich nicht mit E-Mail/Passwort über die API anmelden. Bitten Sie Ihren Canopy-Administrator, ein dediziertes Service-Konto mit einem lokalen Passwort für die Automatisierung zu erstellen.
Token verwenden
curl https://{ihr-slug}-canopy.rhizo-tech.org/api/v1/cards \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Berechtigungen
Die API setzt dieselben RBAC-Regeln wie die Web-Benutzeroberfläche durch. Jeder mutierende Endpunkt prüft sowohl die Anwendungsrolle des Aufrufers als auch alle Stakeholder-Rollen, die er auf der betroffenen Karte hält. Es gibt keine separaten „API-Berechtigungen" oder Service-Account-Umgehungen – Automatisierungsskripte laufen mit den Berechtigungen des Benutzers, dessen Token sie verwenden.
Wenn eine Anfrage mit 403 Forbidden fehlschlägt, ist das Token gültig, aber dem Benutzer fehlt die erforderliche Berechtigung. Siehe die Seite Benutzer & Rollen für die Berechtigungsübersicht.
Häufige Endpunktgruppen
Die Referenz in der Seitenleiste ist die vollständige Quelle der Wahrheit; die nachstehende Tabelle ist eine schnelle Übersicht der am häufigsten verwendeten Gruppen:
| Präfix | Zweck |
|---|---|
/auth | Anmeldung, Registrierung, SSO-Callback, Token-Aktualisierung, aktuelle Benutzerinformationen |
/cards | CRUD auf Karten (die Kernentität), Hierarchie, Verlauf, Genehmigung, CSV-Export |
/relations | CRUD auf Relationen zwischen Karten |
/metamodel | Kartentypen, Felder, Abschnitte, Subtypen, Relationstypen |
/reports | Dashboard-KPIs, Portfolio, Matrix, Lebenszyklus, Abhängigkeiten, Kosten, Datenqualität |
/bpm | Business Process Management – Diagramme, Elemente, Flussversionen, Bewertungen |
/ppm | Project Portfolio Management – Initiativen, Statusberichte, WBS, Aufgaben, Kosten, Risiken |
/turbolens | KI-gestützte Analyse (Anbieter, Duplikate, Architektur-KI) |
/risks | EA-Risikoregister (TOGAF Phase G) |
/diagrams | DrawIO-Diagramme |
/soaw | Statement of Architecture Work-Dokumente |
/adr | Architecture Decision Records |
/users, /roles | Benutzer- und Rollenverwaltung (nur Admin) |
/settings | Anwendungseinstellungen (Logo, Währung, SMTP, KI, Modul-Umschalter) |
/servicenow | Bidirektionale ServiceNow-CMDB-Synchronisierung |
/events, /notifications | Prüfpfad und Benutzerbenachrichtigungen (inkl. SSE-Stream) |
Paginierung, Filterung und Sortierung
Listen-Endpunkte akzeptieren einen konsistenten Satz von Abfrageparametern:
| Parameter | Beschreibung |
|---|---|
page | Seitennummer (1-basiert) |
page_size | Einträge pro Seite (Standard 50, max. 200) |
sort_by | Feld, nach dem sortiert werden soll (z. B. name, updated_at) |
sort_dir | asc oder desc |
search | Freitextfilter (wo unterstützt) |
Ressourcenspezifische Filter sind pro Endpunkt in der Referenz der Seitenleiste dokumentiert (z. B. akzeptiert /cards type, status, parent_id, approval_status).
Echtzeitereignisse (Server-Sent Events)
GET /api/v1/events/stream ist eine langlebige SSE-Verbindung, die Ereignisse überträgt, sobald sie auftreten (Karte erstellt, aktualisiert, genehmigt usw.). Die Web-Benutzeroberfläche verwendet sie, um Badges und Listen ohne Polling zu aktualisieren. Jeder HTTP-Client, der SSE unterstützt, kann sich anmelden – nützlich zum Erstellen von Echtzeit-Dashboards oder externen Benachrichtigungsbrücken.
Code-Generierung
Da die API vollständig durch OpenAPI 3.1 beschrieben ist, können Sie typsichere Clients in jeder wichtigen Programmiersprache generieren:
# Schema herunterladen
curl https://docs.rhizo-tech.org/api/openapi.json -o canopy-openapi.json
# Python-Client generieren
openapi-generator-cli generate \
-i canopy-openapi.json \
-g python \
-o ./canopy-client-py
# …oder TypeScript, Go, Java, C# usw.
Für Python-Automatisierung ist der einfachste Weg in der Regel httpx oder requests mit handgeschriebenen Aufrufen – die API ist klein genug, dass ein Generator selten den Aufwand wert ist.
Ratenbegrenzung
Authentifizierungssensitive Endpunkte (Anmeldung, Registrierung, Passwort-Zurücksetzen) werden ratenbegrenzt, um Brute-Force-Angriffe zu verhindern. Andere Endpunkte sind derzeit nicht ratenbegrenzt; für intensive Automatisierungsskripte, bitte clientseitig drosseln.
Versionierung und Stabilität
- Die API ist über den Präfix
/api/v1versioniert. Eine brechende Änderung würde/api/v2parallel einführen. - Innerhalb von
v1können additive Änderungen (neue Endpunkte, neue optionale Felder) in Minor- und Patch-Releases erscheinen. Entfernungen oder Vertragsänderungen sind einem Major-Versions-Sprung vorbehalten. - Die aktuelle Version wird von
GET /api/healthgemeldet, sodass Sie Upgrades aus der Automatisierung erkennen können.
Fehlerbehebung
| Problem | Lösung |
|---|---|
401 Unauthorized | Token fehlt, ist fehlerhaft oder abgelaufen. Authentifizieren Sie sich erneut über /auth/login oder /auth/refresh. |
403 Forbidden | Token ist gültig, aber dem Benutzer fehlt die erforderliche Berechtigung. Überprüfen Sie die Rolle des Benutzers in Benutzer & Rollen. |
422 Unprocessable Entity | Pydantic-Validierung fehlgeschlagen. Der Antwortinhalt listet auf, welche Felder ungültig sind und warum. |