Introduction

Les API Docebo vous permettent de connecter le système de gestion de la formation avec d'autres applications. Vous pouvez les utiliser, par exemple, pour automatiser des tâches et partager des informations entre systèmes. 

Les API fournissent des endpoints (points de terminaison) à travers lesquels vous pouvez effectuer une variété d'actions sur votre plateforme : gérer des utilisateurs, administrer des cours, récupérer des données, et ainsi de suite. Pour plus d’informations sur les actions disponibles, consultez l'article Aperçu des services et points de terminaison d’API.

De plus, vous pouvez interagir avec les API en utilisant l’explorateur d'API, ce qui vous permet de tester et d'utiliser les endpoints à partir d'une interface web, sans avoir à programmer une intégration.

Cet article fournit des informations générales applicables à toutes les API Docebo. 

Explorateur d’API

La documentation de référence et un environnement de test pour toutes les API Docebo publiquement disponibles sont accessibles au sein de votre plateforme, via l'interface de l’Explorateur d'API, accessible à l’adresse suivante : <URL de votre plateforme>/api-browser. Cette documentation est constamment mise à jour en même temps que votre plateforme.

Pour une introduction à l'utilisation de l’explorateur d'API, consultez l'article Premiers pas avec l'explorateur d’API de Docebo. 

Veuillez noter que, dans certains rares cas, les attributs générés dynamiquement dans les données JSON ne peuvent pas faire l’objet d’un rendu correct dans l'interface utilisateur de la documentation de référence. Cette problématique peut vous empêcher de tester l'API directement à partir de la documentation elle-même. Dans ce cas, nous vous suggérons d'utiliser un outil dédié (par exemple, Postman).

URL de base pour les appels API

L'URL de base pour tous les appels API est celle de votre plateforme. Par exemple, si l’explorateur d’API montre le chemin de point de terminaison suivant :

 /course/v1/courses

Cela signifie que l'URL complète de la requête doit être construite comme suit :

<URL de votre plateforme>/course/v1/courses

Version actuelle

La version par défaut de l'API actuellement exposée est la version 1 (v1). Cependant, à l'avenir, il est possible que des microservices spécifiques exposent des versions ultérieures (v2, v3,..). La version de l'API que vous souhaitez utiliser est spécifiée dans l'URL de l'endpoint. Par exemple :

GET /learn/v1/location

Méthodes de requête HTTP

Conformément aux directives REST, les API de Docebo requièrent l’utilisation d’une méthode HTTP appropriée pour les types d'appels spécifiques effectués vers le serveur. La structure de l'API Docebo suit cette directive chaque fois que cela est techniquement possible, y compris :

Requêtes GET

Utilisées pour récupérer des représentations des ressources

Requêtes POST

Utilisées pour créer de nouvelles ressources

Requêtes PUT

Utilisées pour mettre à jour les ressources existantes

Requêtes DELETE

Utilisées pour supprimer des ressources

Schéma

Toutes les API sont accessibles avec les protocoles HTTP et HTTPS. Nous vous suggérons fortement d'utiliser le protocole HTTPS afin de protéger les informations sensibles transférées de votre système vers Docebo (et inversement). Toutes les requêtes et réponses d’API doivent être au format JSON.

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

Réponse :

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

Points de terminaison de traitement par lots

Concernant les règles décrites précédemment pour les méthodes de requête HTTP, certaines exceptions s'appliquent à certains endpoints utilisés pour la création ou la mise à jour en masse de ressources. Dans ces cas, les appels HTTP POST peuvent également être utilisés pour mettre à jour des ressources existantes et en créer de nouvelles dans le même appel API. L'objectif est de minimiser le nombre d'appels API effectués par le client et d'exploiter au maximum le mécanisme de découpage des opérations inhérentes à ce type d'appel. Ces endpoints sont normalement identifiés par le suffixe /batch :

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

À noter : vous ne pouvez pas envoyer plusieurs appels en parallèle aux API de traitement par lots.

Paramètres

Il existe trois façons de transmettre des paramètres aux API de Docebo : le chemin, la chaîne de requête, et le corps de la requête. 

Paramètres du chemin :

Il existe des cas où les paramètres sont insérés directement dans la structure de l'URL de l'endpoint. Ce type de paramètre contient généralement des ID immuables, mais dans certains cas, il peut contenir des noms de ressources différents (autres que ID).

Voici un exemple d'URL d'un point de terminaison acceptant un paramètre de chemin :

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

Paramètres de la chaîne de requête :

Les paramètres de la chaîne de requête sont principalement utilisés pour vous permettre de filtrer, paginer et (de manière générale) modifier la réponse qui sera renvoyée suite à un appel d’API. Le format des paramètres de la chaîne de requête est basé sur l’URL complète de la ressource suivie d'un point d'interrogation et des paramètres optionnels :

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

Paramètres du corps de la requête :

Pour les appels d’API PUT et POST, vous devez transmettre les paramètres dans le corps de la requête au format JSON. À partir du volet API Reference (référence API), vous devriez voir les paramètres appropriés pouvant être envoyés à un endpoint donné pour chaque point de terminaison.

Paramètres autres que ID (identifiants secondaires)

Pour certaines ressources, les API Docebo supportent des références à des paramètres autres que ID, à l’image des codes de branches. Cependant, notez bien que contrairement aux ID uniques, ces valeurs sont mutables et peuvent ne pas être uniques au sein de votre plateforme. L’API répondra avec une erreur HTTP 400 dans ces cas.

Si vous prévoyez d'utiliser des API avec des références non-ID, l'unicité de ces références doit être vérifiée et garantie par vous. De plus, vous devez explicitement communiquer à l'endpoint qu'il doit fonctionner en mode non-ID, en définissant le paramètre use_secondary_identifier sur true.

Par exemple, l'endpoint GET /manage/v1/orgchart/{branch_id} peut accepter à la fois l'ID interne unique ou le code de branche alphanumérique. Pour utiliser le code de branche, vous devez transmettre la chaîne de requête use_secondary_identifier paramétrée sur true.

Dans le cas d'une branche dont le code assigné est code1562, l'URL de requête résultante est :

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

Bibliothèques clientes des API

Actuellement, Docebo ne fournit aucune bibliothèque cliente pour les API Docebo. Vous devez configurer votre propre package pour commencer à programmer avec les API Docebo.

Limitations des appels API

Pour garantir des performances optimales et la disponibilité des API pour tous les clients, les API de Docebo sont limitées à 1 000 appels d’API par heure depuis chaque adresse IP.

Gestion des redirections HTTP

Actuellement, aucune des API Docebo n'utilise de redirection. Cependant, nous comprenons que cela pourrait être nécessaire à l'avenir pour gérer certains cas spécifiques. Pour cette raison, nous vous invitons à considérer un code 3xx HTTP comme une réponse possible pour tous les endpoints. Étant donné qu’il ne s’agit pas d’un code représentant une erreur, nous vous conseillons de suivre la redirection elle-même.

Pagination et tri

Toutes les requêtes qui renvoient un nombre variable (et potentiellement important) d'éléments sont paginées par défaut. La valeur par défaut pour le nombre d'éléments par page est fixée à 10 éléments. Veuillez noter que cette valeur pourrait être différente pour certains points de terminaison pour des raisons de performance. Vous pouvez modifier cette limite en utilisant le paramètre page_size, qui est transmis à l'endpoint à l’aide d’une chaîne de requête. Le paramètre accepte des valeurs entre 1 et 200. Les valeurs en dehors de ces seuils ne seront pas considérées comme valides. Le paramètre page vous permet d'obtenir des données d'une page spécifique dans les résultats renvoyés. La valeur par défaut pour ce paramètre est 1, ce qui correspond à la première page de résultats. Même dans ce cas, le paramètre peut être transmis à l'API via une chaîne de requête :

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

Les liens de navigation entre les pages de résultats peuvent être prégénérés par l'API elle-même, afin de bénéficier en réponse d’un tableau de liens HTTP pouvant être suivis directement. Cette fonctionnalité est désactivée par défaut. Pour l'activer, vous pouvez régler le paramètre get_cursor sur 1 dans la chaîne de requête de l'appel d’API :

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

Réponse :

{
 {[...JSON-OMIS...]
 "_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"
   }
 }
}

Vous pouvez également contrôler l'ordre de tri des enregistrements renvoyés par l'appel d’API. Le paramètre utilisable à cet effet est sort_attr. Il peut être transmis via la chaîne de requête. Les valeurs que peut prendre ce paramètre sont différentes d'un point de terminaison à l'autre en raison de l’hétérogénéité des ressources. Nous vous conseillons de vérifier les valeurs disponibles pour ces paramètres dans chaque description d’endpoint depuis le volet API Reference. Dans tous les cas, vous ne pouvez spécifier qu'un seul attribut à utiliser pour le tri, et vous ne pouvez pas en spécifier plusieurs consécutivement. La valeur par défaut du paramètre dépend du point de terminaison. La direction de tri peut être gérée avec le paramètre sort_dir. Les valeurs acceptables sont asc pour un ordre croissant et desc pour un ordre décroissant. La valeur par défaut est toujours décroissante :

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

Codes d'erreur

Les API de Docebo renvoient des codes d'erreur HTTP standard pour indiquer qu’une requête a réussi ou non. Spécifiquement, chaque client doit être capable de gérer les codes HTTP suivants :

Politique de modification des API

Bien que Docebo s'efforce d’apporter des modifications rétrocompatibles à ses API, lorsque cela n'est pas possible, les clients en sont informés conformément aux politiques énoncées dans ce chapitre. 

Modifications rétrocompatibles

Considérez les modifications énumérées ci-dessous comme rétrocompatibles. Nous vous invitons à structurer votre code pour qu'il puisse prendre en charge de telles modifications aux API. Ce type de modification se produit normalement sans que les clients en soient avertis. Elles peuvent inclure :

• Ajout de nouveaux points de terminaison
• Ajout de nouveaux paramètres optionnels aux points de terminaison d’API existants
• Ajout de nouvelles propriétés aux réponses des API
• Modification de l'ordre des propriétés dans les réponses des API
• Toute mise à jour de la documentation de référence des API

Modifications non rétrocompatibles 

En cas de modification des API susceptible d’avoir un impact sur des intégrations existantes, les clients sont informés un certain temps à l'avance par une précommunication sur la page des mises à jour des produits. Cette période de préavis peut varier en raison de considérations techniques et d'utilisation, mais généralement la précommunication est effectuée au moins un mois avant que le changement n'entre en vigueur. 

→ Cette règle ne s'applique pas en cas de vulnérabilités de sécurité critiques. Dans de tels cas, un correctif est appliqué immédiatement, et une communication peut apparaître sur la page Mises à jour produit pendant ou peu après son déploiement.

Journal de changement des API

Docebo informe les clients de toute modification non rétrocompatible ou dépréciation de ses API via la page des mises à jour des produits. Si vous voyez une communication relative aux API sur cette page, vous pouvez alors vous référer à la référence officielle sur les API (https://<votresousdomaine.docebosaas.com>/api-browser/) pour obtenir une compréhension complète des changements survenus.

De plus, l'article Appels d’API dépréciés et modifiés fournit des détails sur les points de terminaison d’API qui ont été modifiés ou supprimés depuis janvier 2023. (Cependant, il n'inclut pas les appels d’API qui ont été introduits ou publiés.)

Explorateur d'API et champs supplémentaires

Les champs supplémentaires utilisés sur la plateforme pour la gestion des utilisateurs, des cours, et des inscriptions sont gérés par les Superadmins comme des valeurs dynamiques, et ne peuvent être inclus dans la documentation de l’explorateur d'API, car ils varient d'une plateforme à l'autre. Pour la même raison, il n'est pas possible de tester des champs supplémentaires depuis l’explorateur d'API. À titre d'exemple, si vous voulez filtrer les cours en utilisant la valeur d'un champ supplémentaire de cours où xx est l'ID du champ supplémentaire (tel que field_1, field_2, etc), la chaîne à utiliser serait quelque chose comme :

https://votredomaine.docebosaas.com/learn/v1/enrollments?field_6=3

L'ID à utiliser dans votre requête au lieu de xx sera soit un entier (par exemple, pour les champs supplémentaires de type liste déroulante), une chaîne de caractères (pour un champ supplémentaire de type texte), un tableau, ou une date (pour un champ supplémentaire de type date). Voici quelques exemples :

date :

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

textfield :

'field_6': 'abc'

OU

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

Champs supplémentaires iframe :

Modifiez les valeurs de field_xx et field_xx_yy (yy représentant le champ de la configuration JSON) et utilisez cette syntaxe : '$^speakers^speaker'. La valeur sera soit une chaîne de caractères (pour un champ supplémentaire de type texte) soit un tableau ou une date (pour un champ supplémentaire de type date). Exemples :

date :

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

textfield :

'field6$^textfield': 'abc'

OU

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

Gestion des champs de tableau pour les requêtes GET

Les paramètres de chaîne de requête décrits comme des tableaux doivent être spécifiés différemment selon l'outil que vous utilisez pour consommer l'API :

• Explorateur d'API Docebo : en raison des conversions internes appliquées par cet outil, les paramètres doivent être séparés par une virgule. En outre, si les paramètres sont des chaînes de caractères, ils doivent être entourés de guillemets doubles. Exemple :

  "enrollment_status", "enrollment_completion_percentage”

• Postman (ou clients similaires) : le paramètre doit être suivi de doubles crochets et spécifié autant de fois qu'il y a de valeurs à transmettre. Exemple :

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