Riferimento API
Canopy espone una API REST completa che alimenta tutto ciò che è possibile fare nell'interfaccia web. È possibile utilizzarla per automatizzare gli aggiornamenti dell'inventario, integrarla con pipeline CI/CD, creare pannelli di controllo personalizzati o estrarre dati di AE in altri strumenti (BI, GRC, ITSM, fogli di calcolo).
La specifica OpenAPI 3.1 completa è disponibile nella sezione Endpoint API della barra laterale — ogni endpoint, parametro e schema di risposta, rigenerato dal codice sorgente del backend ad ogni rilascio.
URL base
Tutti gli endpoint API si trovano sotto il prefisso /api/v1. L'URL del vostro ambiente Canopy segue il modello:
https://{vostro-slug}-canopy.rhizo-tech.org/api/v1
Sostituite {vostro-slug} con lo slug della vostra organizzazione, che appare nel vostro account Rhizo e nell'URL usato per accedere a Canopy.
L'unica eccezione è l'endpoint di verifica dello stato, montato su /api/health (senza prefisso di versione).
Riferimento API interattivo
La specifica OpenAPI 3.1 completa è disponibile nella sezione Endpoint API della barra laterale. Ogni pagina di endpoint include un playground interattivo dove è possibile inserire il proprio bearer token ed eseguire richieste in tempo reale contro il proprio ambiente Canopy.
La specifica grezza è anche scaricabile per i generatori di codice:
https://docs.rhizo-tech.org/api/openapi.json
Per utilizzare il playground interattivo, aprire qualsiasi pagina di endpoint nella sezione Endpoint API della barra laterale, inserire il proprio bearer token nel campo Authorization, compilare i parametri e fare clic su Send.
Autenticazione
Tutti gli endpoint eccetto /auth/*, il controllo dello stato e i portali web pubblici richiedono un JSON Web Token inviato nell'intestazione Authorization:
Authorization: Bearer <access_token>
Ottenere un token
POST /api/v1/auth/login con il proprio indirizzo email e password:
curl -X POST https://{vostro-slug}-canopy.rhizo-tech.org/api/v1/auth/login \
-H "Content-Type: application/json" \
La risposta contiene un access_token:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer"
}
I token sono validi per 24 ore. Usare POST /api/v1/auth/refresh per estendere una sessione senza reinserire le credenziali.
Se la propria organizzazione utilizza il Single Sign-On, non è possibile accedere con email e password tramite l'API. Chiedere al proprio amministratore Canopy di creare un account di servizio dedicato con una password locale per l'automazione.
Usare il token
curl https://{vostro-slug}-canopy.rhizo-tech.org/api/v1/cards \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Permessi
L'API applica le stesse regole RBAC dell'interfaccia web. Ogni endpoint di mutazione verifica sia il ruolo a livello di applicazione del chiamante sia i ruoli stakeholder che detiene sulla scheda interessata. Non esistono «permessi API» separati né eccezioni per account di servizio — gli script di automazione vengono eseguiti con i permessi dell'utente il cui token utilizzano.
Se una richiesta fallisce con 403 Forbidden, il token è valido ma all'utente manca il permesso richiesto. Consultare la pagina Utenti e ruoli per il registro dei permessi.
Gruppi di endpoint comuni
Il riferimento nella barra laterale è la fonte completa di verità; la tabella seguente è una mappa rapida dei gruppi più utilizzati:
| Prefisso | Scopo |
|---|---|
/auth | Accesso, registrazione, callback SSO, rinnovo token, informazioni utente corrente |
/cards | CRUD sulle schede (l'entità principale), gerarchia, cronologia, approvazione, esportazione CSV |
/relations | CRUD sulle relazioni tra schede |
/metamodel | Tipi di scheda, campi, sezioni, sottotipi, tipi di relazione |
/reports | KPI del pannello, portafoglio, matrice, ciclo di vita, dipendenze, costo, qualità dei dati |
/bpm | Gestione dei processi aziendali — diagrammi, elementi, versioni del flusso, valutazioni |
/ppm | Gestione del portafoglio progetti — iniziative, report di stato, WBS, task, costi, rischi |
/turbolens | Analisi basata su AI (fornitori, duplicati, architettura AI) |
/risks | Registro dei rischi di AE (Fase G TOGAF) |
/diagrams | Diagrammi DrawIO |
/soaw | Documenti Dichiarazione di Lavoro Architetturale |
/adr | Record di Decisioni Architetturali |
/users, /roles | Amministrazione di utenti e ruoli (solo amministratori) |
/settings | Impostazioni dell'applicazione (logo, valuta, SMTP, AI, attivazione moduli) |
/servicenow | Sincronizzazione bidirezionale con ServiceNow CMDB |
/events, /notifications | Registro di audit e notifiche utente (incluso il flusso SSE) |
Paginazione, filtraggio e ordinamento
Gli endpoint di elenco accettano un insieme coerente di parametri di query:
| Parametro | Descrizione |
|---|---|
page | Numero di pagina (a base 1) |
page_size | Elementi per pagina (predefinito 50, massimo 200) |
sort_by | Campo per cui ordinare (ad es. name, updated_at) |
sort_dir | asc o desc |
search | Filtro di testo libero (dove supportato) |
I filtri specifici per risorsa sono documentati per ogni endpoint nel riferimento della barra laterale (ad es. /cards accetta type, status, parent_id, approval_status).
Eventi in tempo reale (Server-Sent Events)
GET /api/v1/events/stream è una connessione SSE a lunga durata che invia eventi non appena si verificano (scheda creata, aggiornata, approvata, ecc.). L'interfaccia web la usa per aggiornare badge ed elenchi senza polling. Qualsiasi client HTTP che supporti SSE può iscriversi — utile per creare pannelli in tempo reale o bridge di notifica esterni.
Generazione di codice
Poiché l'API è completamente descritta da OpenAPI 3.1, è possibile generare client con tipi sicuri in qualsiasi linguaggio principale:
# Scaricare lo schema
curl https://docs.rhizo-tech.org/api/openapi.json -o canopy-openapi.json
# Generare un client Python
openapi-generator-cli generate \
-i canopy-openapi.json \
-g python \
-o ./canopy-client-py
# …o TypeScript, Go, Java, C#, ecc.
Per l'automazione in Python, il percorso più semplice è di solito httpx o requests con chiamate scritte a mano — l'API è abbastanza piccola da rendere un generatore raramente necessario come dipendenza.
Limitazione della velocità
Gli endpoint sensibili per l'autenticazione (accesso, registrazione, reimpostazione password) hanno un limite di velocità per proteggersi dagli attacchi di forza bruta. Gli altri endpoint non sono attualmente limitati in velocità; per script di automazione intensivi, implementare la limitazione lato client.
Versioning e stabilità
- L'API è versionata tramite il prefisso
/api/v1. Una modifica incompatibile introdurrebbe/api/v2accanto ad esso. - All'interno di
v1, le modifiche additive (nuovi endpoint, nuovi campi opzionali) possono essere rilasciate in versioni minori e di patch. Le rimozioni o le modifiche al contratto sono riservate a un salto di versione maggiore. - La versione corrente è riportata da
GET /api/health, così è possibile rilevare gli aggiornamenti dall'automazione.
Risoluzione dei problemi
| Problema | Soluzione |
|---|---|
401 Unauthorized | Il token è mancante, malformato o scaduto. Autenticarsi nuovamente tramite /auth/login o /auth/refresh. |
403 Forbidden | Il token è valido ma all'utente manca il permesso richiesto. Verificare il ruolo dell'utente in Utenti e ruoli. |
422 Unprocessable Entity | La validazione Pydantic ha fallito. Il corpo della risposta elenca quali campi non sono validi e perché. |