API-reference
Canopy eksponerer et komplet REST API, der driver alt, hvad du kan gøre i webgrænsefladen. Du kan bruge det til at automatisere lageropdateringer, integrere med CI/CD-pipelines, bygge brugerdefinerede dashboards eller trække EA-data ind i andre værktøjer (BI, GRC, ITSM, regneark).
Den komplette OpenAPI 3.1-specifikation er tilgængelig i sektionen API-endepunkter i sidebjælken — hvert endepunkt, parameter og responsform, genskabt fra backendkilden ved hver udgivelse.
Basis-URL
Alle API-endepunkter findes under præfikset /api/v1. Din Canopy-miljø-URL følger mønsteret:
https://{dit-slug}-canopy.rhizo-tech.org/api/v1
Erstat {dit-slug} med din organisations slug, som vises i din Rhizo-konto og i den URL, du bruger til at tilgå Canopy.
Den eneste undtagelse er sundhedstjek-endepunktet, som er monteret på /api/health (uden versionspræfiks).
Interaktiv API-reference
Den komplette OpenAPI 3.1-specifikation er tilgængelig i sektionen API-endepunkter i sidebjælken. Hver endepunktsside inkluderer en interaktiv legeplads, hvor du kan indtaste dit bearer-token og udføre live-forespørgsler mod dit Canopy-miljø.
Den rå specifikation kan også downloades til kodegeneratorer:
https://docs.rhizo-tech.org/api/openapi.json
For at bruge den interaktive legeplads skal du åbne en hvilken som helst endepunktsside i sektionen API-endepunkter i sidebjælken, indtaste dit bearer-token i feltet Authorization, udfylde parametrene og klikke på Send.
Autentificering
Alle endepunkter undtagen /auth/*, sundhedstjekket og offentlige webportaler kræver et JSON Web Token sendt i Authorization-headeren:
Authorization: Bearer <access_token>
Hentning af token
POST /api/v1/auth/login med din e-mail og adgangskode:
curl -X POST https://{dit-slug}-canopy.rhizo-tech.org/api/v1/auth/login \
-H "Content-Type: application/json" \
Svaret indeholder et access_token:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer"
}
Tokens er gyldige i 24 timer. Brug POST /api/v1/auth/refresh til at forlænge en session uden at genindtaste legitimationsoplysninger.
Hvis din organisation bruger Single Sign-On, kan du ikke logge ind med e-mail og adgangskode via API'et. Bed din Canopy-administrator om at oprette en dedikeret servicekonto med en lokal adgangskode til automatiseringsbrug.
Brug af token
curl https://{dit-slug}-canopy.rhizo-tech.org/api/v1/cards \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Tilladelser
API'et håndhæver de samme RBAC-regler som webgrænsefladen. Hvert muterende endepunkt kontrollerer både kalderens applikationsniveau-rolle og eventuelle interessentroller, de besidder på det berørte kort. Der er ingen separate "API-tilladelser" eller servicekontoombygninger — automatiseringsscripts kører med tilladelserne for den bruger, hvis token de anvender.
Hvis en forespørgsel mislykkes med 403 Forbidden, er tokenet gyldigt, men brugeren mangler den nødvendige tilladelse. Se siden Brugere og roller for tilladelsesregistret.
Almindelige endepunktsgrupper
Referencen i sidebjælken er den komplette kilde til sandhed; tabellen nedenfor er et hurtigt overblik over de mest brugte grupper:
| Præfiks | Formål |
|---|---|
/auth | Login, registrering, SSO-callback, token-fornyelse, aktuel brugerinfo |
/cards | CRUD på kort (kerneobjektet), hierarki, historik, godkendelse, CSV-eksport |
/relations | CRUD på relationer mellem kort |
/metamodel | Korttyper, felter, sektioner, undertyper, relationstyper |
/reports | Dashboard-KPI'er, portefølje, matrix, livscyklus, afhængigheder, omkostninger, datakvalitet |
/bpm | Forretningsproceshåndtering — diagrammer, elementer, flowversioner, vurderinger |
/ppm | Projektporteføljehåndtering — initiativer, statusrapporter, WBS, opgaver, omkostninger, risici |
/turbolens | AI-drevet analyse (leverandører, dubletter, arkitektur-AI) |
/risks | EA-risikoregister (TOGAF fase G) |
/diagrams | DrawIO-diagrammer |
/soaw | Statement of Architecture Work-dokumenter |
/adr | Architecture Decision Records |
/users, /roles | Bruger- og rolleadministration (kun administrator) |
/settings | Applikationsindstillinger (logo, valuta, SMTP, AI, modulskift) |
/servicenow | Tovejs ServiceNow CMDB-synkronisering |
/events, /notifications | Revisionsspor og brugernotifikationer (inkl. SSE-stream) |
Paginering, filtrering og sortering
Listeendepunkter accepterer et konsistent sæt forespørgselsparametre:
| Parameter | Beskrivelse |
|---|---|
page | Sidenummer (1-baseret) |
page_size | Elementer pr. side (standard 50, maks. 200) |
sort_by | Felt at sortere efter (f.eks. name, updated_at) |
sort_dir | asc eller desc |
search | Fritekstfilter (hvor understøttet) |
Ressourcespecifikke filtre er dokumenteret pr. endepunkt i sidebjælkereferencen (f.eks. /cards accepterer type, status, parent_id, approval_status).
Realtidshændelser (Server-Sent Events)
GET /api/v1/events/stream er en langvarig SSE-forbindelse, der pusher hændelser, efterhånden som de sker (kort oprettet, opdateret, godkendt osv.). Webgrænsefladen bruger den til at opdatere badges og lister uden polling. Enhver HTTP-klient, der understøtter SSE, kan abonnere — nyttigt til at bygge realtidsdashboards eller eksterne notifikationsbroer.
Kodegenerering
Da API'et er fuldt beskrevet af OpenAPI 3.1, kan du generere typesikre klienter i alle store programmeringssprog:
# Download specifikationen
curl https://docs.rhizo-tech.org/api/openapi.json -o canopy-openapi.json
# Generer en Python-klient
openapi-generator-cli generate \
-i canopy-openapi.json \
-g python \
-o ./canopy-client-py
# ...eller TypeScript, Go, Java, C# osv.
Til Python-automatisering er den nemmeste vej typisk httpx eller requests med håndskrevne kald — API'et er lille nok til, at en generator sjældent er prisen for afhængigheden værd.
Hastighedsbegrænsning
Autentificeringssuivrige endepunkter (login, registrering, nulstilling af adgangskode) er hastighedsbegrænsede for at beskytte mod brute-force-angreb. Andre endepunkter er i øjeblikket ikke hastighedsbegrænsede; implementer klientsidebegrænsning for intensive automatiseringsscripts.
Versionering og stabilitet
- API'et er versioneret via præfikset
/api/v1. En brydende ændring ville introducere/api/v2parallelt. - Inden for
v1kan additive ændringer (nye endepunkter, nye valgfrie felter) udgives i mindre og patch-udgivelser. Fjernelser eller kontraktændringer er reserveret til en stigning i hovednummeret. - Den aktuelle version rapporteres af
GET /api/health, så du kan registrere opgraderinger fra automatisering.
Fejlfinding
| Problem | Løsning |
|---|---|
401 Unauthorized | Token mangler, er misdannet eller udløbet. Godkend igen via /auth/login eller /auth/refresh. |
403 Forbidden | Token er gyldigt, men brugeren mangler den nødvendige tilladelse. Kontroller brugerens rolle under Brugere og roller. |
422 Unprocessable Entity | Pydantic-validering mislykkedes. Svarteksten angiver, hvilke felter der er ugyldige og hvorfor. |