Introduzione

Le API Docebo consentono di connettere il sistema di gestione della formazione con altre applicazioni. Possono essere utilizzate, ad esempio, per automatizzare le attività e condividere informazioni tra sistemi. 

Le API forniscono endpoint attraverso i quali si possono eseguire una varietà di azioni sulla piattaforma, come la gestione degli utenti, l'amministrazione dei corsi, o anche il recupero dei dati. Per ulteriori informazioni sulle azioni disponibili, consultare l'articolo Panoramica dei servizi e degli endpoint API.

Inoltre, è possibile interagire con le API utilizzando l'API browser, che consente di testare e utilizzare gli endpoint da un'interfaccia web, senza dover sviluppare un'integrazione.

Questo articolo fornisce alcune informazioni generali applicabili a tutte le API Docebo. 

API browser

La documentazione di riferimento e un ambiente di test per tutte le API Docebo pubbliche sono disponibili in piattaforma, tramite l'interfaccia dell'API browser, accessibile come segue : <URL della piattaforma>/api-browser. Questa documentazione è costantemente aggiornata insieme alla piattaforma.

Per scoprire come utilizzare l'API browser, consultare l'articolo Primi passi con l'API browser di Docebo. 

Si noti che, in alcuni rari casi, gli attributi generati dinamicamente nei dati JSON non possono essere resi correttamente dall'interfaccia utente della documentazione di riferimento. Questo potrebbe impedire di testare l'API direttamente dalla documentazione stessa. In questo caso, si suggerisce di utilizzare uno strumento dedicato (ad esempio, Postman).

URL di base per le chiamate API

L'URL di base per tutte le chiamate API è l'URL della piattaforma. Ad esempio, se nell'API browser si vede un percorso di endpoint come:

 /course/v1/courses

Questo significa che l'URL della richiesta completa deve essere formato come segue:

<URL della piattaforma>/course/v1/courses

Versione attuale

La versione predefinita dell'API attualmente esposta è la versione 1 (v1). Tuttavia, in futuro, potrebbero esserci microservizi specifici esponendo versioni successive (v2, v3,..). La versione dell'API che si intende utilizzare è specificata nell'URL dell'endpoint. Ad esempio:

GET /learn/v1/location

Metodi di richieste HTTP

Seguendo le linee guida REST, le API Docebo richiedono di applicare un metodo di richiesta HTTP appropriato ai tipi specifici di chiamate effettuate al server. La struttura dell'API Docebo segue questa linea guida ovunque sia tecnicamente possibile, includendo:

Richieste GET

Utilizzate per recuperare le rappresentazioni delle risorse

Richieste POST

Utilizzate per creare nuove risorse

Richieste PUT

Utilizzate per aggiornare le risorse esistenti

Richieste DELETE

Utilizzate per l'eliminazione delle risorse

Schema

Tutte le API sono accessibili utilizzando sia il protocollo HTTP che il protocollo HTTPS. Si consiglia vivamente di utilizzare il protocollo HTTPS al fine di proteggere le informazioni sensibili trasferite dal sistema a Docebo (e viceversa). Tutte le richieste e le risposte delle API dovrebbero essere in formato JSON.

curl -i -X GET http:///manage/v1/group -H 'Authorization: Bearer f7bfc5f78877f6ec321a650b10e8aa3d32a18f32'

Risposta:

HTTP/1.1 200 OK
Server: openresty
Date: Tue, 29 May 2018 08:35:06 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 479
Connection: keep-alive
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: X-Docebo-Api-Version
X-Docebo-Api-Version: 1.0.0
X-UA-Compatible: IE=Edge,chrome=1
X-Frame-Option: SAMEORIGIN
X-XSS-Protection: 1
Access-Control-Allow-Origin: *
X-Docebo-Backyard: manage
Front-End-Https: on

Endpoint batch

Riguardo alle regole descritte in precedenza per i metodi di richieste HTTP, alcune eccezioni si applicano a certi endpoint utilizzati per la creazione o l'aggiornamento massivo di risorse. In questi casi, le chiamate HTTP POST possono essere utilizzate anche per aggiornare le risorse esistenti e crearne di nuove tramite la stessa chiamata API. L'obiettivo di questo è minimizzare il numero di chiamate API effettuate dal client e sfruttare il più possibile il meccanismo di chunking (suddivisione) delle operazioni inerenti a questo tipo di chiamata. Questi endpoint sono normalmente identificati dal suffisso /batch:

POST https:///manage/v1/user/batch

Attenzione! Non è possibile inviare chiamate concorrenti per le API batch.

Parametri

Esistono tre modi per inviare i parametri alle API Docebo: il percorso, la stringa di query, e il corpo della richiesta. 

Parametri di percorso:

Ci sono casi in cui i parametri vengono inseriti direttamente nella struttura dell'URL dell'endpoint. Questo tipo di parametro generalmente contiene ID immutabili, ma in alcuni casi può contenere nomi di risorse non-ID.

Il seguente è un esempio di URL di un endpoint che accetta un parametro di percorso:

PUT https:///learn/v1/courses/{id}

Parametri della stringa di query:

I parametri della stringa di query sono principalmente utilizzati per consentire di filtrare, impaginare e (in generale) modificare la risposta che verrà restituita da una chiamata API. Il formato per i parametri della stringa di query è l'URL completo della risorsa seguito da un punto interrogativo e dai parametri opzionali:

GET https:///learn/v1/enrollments?id_user{user_id}

Parametri del corpo della richiesta:

Per le chiamate API PUT e POST, si dovrebbero inviare i parametri nel corpo della richiesta in formato JSON. Dal pannello API Reference (riferimento API), dovrebbero essere visualizzati i parametri idonei per essere inviati a ciascun endpoint specifico.

Parametri non-ID (identificatori secondari)

Per alcune risorse, le API Docebo supportano l'utilizzo di parametri non-ID, come i codici di ramo. Tuttavia, è importante ricordare che, a differenza degli ID unici, questi valori sono mutabili e potrebbero non essere unici all'interno della piattaforma. L'API risponderà con un errore HTTP 400 in questi casi.

Se si prevede di utilizzare le API con parametri non-ID, l'unicità di tali riferimenti dovrebbe essere verificata e garantita in modo autonomo. Inoltre, si dovrebbe esplicitamente comunicare all'endpoint che deve operare in modalità non-ID, impostando il parametro use_secondary_identifier a true.

Ad esempio, l'endpoint GET /manage/v1/orgchart/{branch_id} può accettare sia l'ID interno unico che il codice di ramo alfanumerico. Se si desidera utilizzare il codice del ramo è necessario inviare la stringa del parametro di query use_secondary_identifier impostata a true.

Nel caso di un ramo il cui codice assegnato è code1562, l'URL della richiesta risultante è:

GET https:///manage/v1/orgchart/code1562?use_secondary_identifier=true

Librerie client delle API

Al momento, Docebo non fornisce alcuna libreria client per le sue API. Si deve impostare il proprio pacchetto per iniziare a programmare con le API Docebo.

Limitazioni delle chiamate API

Per mantenere prestazioni ottimali e garantire che le API siano disponibili a tutti i clienti, le API di Docebo sono limitate a 1.000 chiamate API all'ora da ogni indirizzo IP.

Gestione dei reindirizzamenti HTTP

Attualmente, nessuna delle API di Docebo utilizza i reindirizzamenti. Tuttavia, si riconosce che potrebbero essere necessari in futuro per gestire alcuni casi specifici. Per questo motivo, si invita a considerare un codice 3xx HTTP come una possibile risposta per tutti gli endpoint. Poiché non si tratta di un codice che rappresenta un errore, si dovrebbe seguire il reindirizzamento stesso.

Paginazione e ordinamento

Tutte le richieste che restituiscono un numero variabile (e potenzialmente grande) di elementi sono impaginate per impostazione predefinita. Il valore predefinito per il numero di elementi per pagina è impostato a 10 elementi. Si noti che questo valore potrebbe essere diverso per alcuni endpoint per motivi di prestazioni. È possibile modificare questo limite utilizzando il parametro page_size, che viene passato all'endpoint tramite la stringa di query. Il parametro accetta valori tra 1 e 200. I valori al di fuori di queste soglie non saranno considerati validi. Il parametro page consente di ottenere dati da una pagina specifica all'interno dei risultati restituiti. Il valore predefinito per questo parametro è 1, corrispondente alla prima pagina dei risultati. Anche in questo caso, il parametro può essere passato all'API tramite una stringa di query:

curl -X GET https:///courses?page_size=5&page=2' -H 'Authorization: Bearer 2af6ac532cfef197b00f69639aeeef86621d1975'

I link di navigazione tra le pagine dei risultati possono essere pre-generati dall'API stessa, fornendo un array di link HTTP nella risposta che si possono seguire direttamente. Questa funzionalità è disabilitata per impostazione predefinita. Per attivarla, è possibile impostare il parametro get_cursor a 1 nella stringa di query della chiamata API:

curl -X GET https:///courses?get_cursor=1 -H 'Authorization: Bearer 2af6ac532cfef197b00f69639aeeef86621d1975'

Risposta:

{
 {[...JSON-OMESSO...]
 "_links": {
   "self": {
     "href": "https:///learn/v1/courses?cursor=6b1af27dd7d849c6a0a399439a12ad791abb6708&page=1"
   },
   "next": {
     "href": "https:///learn/v1/courses?cursor=6b1af27dd7d849c6a0a399439a12ad791abb6708&page=2"
   },
   "goto": {
     "href": "https:///learn/v1/courses?cursor=6b1af27dd7d849c6a0a399439a12ad791abb6708&page=__page__"
   },
   "first": {
     "href": "https:///learn/v1/courses?cursor=6b1af27dd7d849c6a0a399439a12ad791abb6708&page=1"
   },
   "last": {
     "href": "https:///learn/v1/courses?cursor=6b1af27dd7d849c6a0a399439a12ad791abb6708&page=2"
   }
 }
}

È possibile inoltre controllare l'ordine di ordinamento dei record restituiti dalla chiamata API. Il parametro utilizzato per determinare tale ordine è sort_attr, il quale può essere passato tramite stringa di query. I valori che questo parametro può assumere variano da un endpoint all'altro, poiché le risorse restituite sono eterogenee. Si consiglia di verificare i valori disponibili per questi parametri nella descrizione di ciascun endpoint nella documentazione API Reference. In ogni caso, è consentito specificare un solo attributo per l'ordinamento e non è possibile indicare attributi di ordinamento consecutivi. Il valore predefinito per il parametro dipende dall'endpoint. La direzione dell'ordinamento può essere gestita tramite il parametro sort_dir, i cui valori accettabili sono asc per un ordine crescente e desc per un ordine decrescente. Il valore predefinito è sempre decrescente:

curl -X GET https:///courses?sort_attr=name&sort_dir=asc' -H 'authorization: Bearer 2af6ac532cfef197b00f69639aeeef86621d1975'

Codici di errore

Le API di Docebo restituiscono i codici di errore HTTP standard per indicare se una richiesta ha avuto successo o meno. Nello specifico, ogni client deve essere in grado di gestire i seguenti codici HTTP:

Politica per le modifiche alle API

Docebo si impegna a mantenere le modifiche alle API retrocompatibili, ma quando questo non è possibile, i clienti vengono informati secondo le politiche stabilite in questo capitolo. 

Modifiche retrocompatibili

Considerare le modifiche elencate di seguito come retrocompatibili. Si invita a strutturare il proprio codice per poter supportare tali modifiche alle API. Questo tipo di modifica avviene in generale senza alcuna notifica ai clienti. Possono includere:

• Aggiunta di nuovi endpoint
• Aggiunta di nuovi parametri opzionali agli endpoint API esistenti
• Aggiunta di nuove proprietà alle risposte delle API
• Modifica dell'ordine delle proprietà nelle risposte API
• Qualsiasi aggiornamento alla documentazione di riferimento API

Modifiche non retrocompatibili 

In caso di modifiche API che potrebbero potenzialmente impattare le integrazioni esistenti, i clienti vengono notificati in anticipo tramite una precomunicazione ("Heads up!") sulla pagina sugli aggiornamenti di prodotto. Il periodo di preavviso può variare a causa di considerazioni tecniche e di utilizzo, ma generalmente la precomunicazione avverrà almeno un mese prima che la modifica entri in vigore. 

→ Questa regola non si applica in caso di vulnerabilità critiche di sicurezza. In tali casi, una correzione viene applicata immediatamente, e una comunicazione può apparire sulla pagina Aggiornamenti di prodotto durante o poco dopo l'implementazione.

Changelog API

Docebo informa i clienti di eventuali modifiche non retrocompatibili o deprecazioni alle API Docebo tramite la pagina sugli aggiornamenti di prodotto. Una volta che si vede una comunicazione relativa alle API su questa pagina, è possibile fare riferimento alla riferimento API ufficiale (https://<il_tuo_sottodominio.docebosaas.com>/api-browser/) per una comprensione completa delle modifiche avvenute.

Inoltre, l'articolo Chiamate API deprecate e modificate fornisce dettagli sugli endpoint API che sono stati modificati o rimossi da gennaio 2023. (Tuttavia, non include le chiamate API che sono state introdotte o rilasciate.)

API browser e campi aggiuntivi

I campi aggiuntivi utilizzati in piattaforma per la gestione di utenti, corsi, e iscrizioni sono gestiti dai Superadmin come valori dinamici, e non possono essere documentati nella documentazione dell'API browser, poiché cambiano da piattaforma a piattaforma. Per la stessa ragione, non è possibile testare i campi aggiuntivi dall'API browser. Ad esempio, se si desidera filtrare i corsi in base a un valore di campo aggiuntivo del corso dove xx è l'ID del campo aggiuntivo (come field_1, field_2, ecc), la stringa da utilizzare sarebbe qualcosa del tipo:

[https://dominio.docebosaas.com/learn/v1/enrollments?field_6=3](https://dominio.docebosaas.com/learn/v1/enrollments?field_6=3)

L'ID da utilizzare nella query al posto di xx sarà un numero intero (ad esempio, per i campi aggiuntivi a tendina), una stringa (per un campo aggiuntivo testo), un array o una data (per un campo aggiuntivo date). Ecco alcuni esempi:

date:

'field_12': {'from': '2018-06-26','to': '2018-06-30'},

textfield:

'field_6': 'abc'

OPPURE

'field_6': ['abc', 'def'], dropdown: 'field_8': 3

campi aggiuntivi iframe:

Estendere field_xx e field_xx_yy (dove yy è il campo dalla configurazione JSON) e utilizzare questa sintassi: '$^speakers^speaker'. Il valore sarà una stringa (per un campo aggiuntivo testo) o un array o una data (per un campo aggiuntivo data). Esempi:

date:

'field_12$^datefield': {'from': '2018-06-26','to': '2018-06-30'},

textfield:

'field6$^textfield': 'abc'

OPPURE

'field6$^textfield': ['abc', 'def']

Gestione dei campi array per le richieste GET

I parametri della stringa di query descritti come array devono essere specificati in modo diverso a seconda dello strumento che si sta utilizzando per consumare l'API:

• API browser di Docebo: a causa delle conversioni interne applicate da questo strumento, i parametri devono essere separati da una virgola. Inoltre, se i parametri sono stringhe, devono essere racchiusi tra virgolette doppie. Esempio:

  "enrollment_status", "enrollment_completion_percentage”

• Postman (o client simili): il parametro deve essere seguito da doppie parentesi quadre e specificato un numero di volte corrispondente ai valori che si intendono inviare. Esempio:

  <ENDPOINT>?learning_plan_id[]=25&learning_plan_id[]=1&extra_fields[]=enrollment_time_spent&extra_fields[]=enrollment_status