Pour les purs geeks, une brève description de l’API du logiciel “Je Lève La Main”

Par Thierry, jeudi 24 mars 2016
Catégories : API, Evaluation, Je Lève La Main - version virtuelle

Qu’est ce que l’API du logiciel “Je Lève La Main” ?

C’est un service web qui vous permet d’avoir accès aux données de l’application, d’en extraire des statistiques et d’utiliser l’ensemble dans vos propres applications.

Vous accédez à l’API via des requêtes http (dans le langage de votre choix) ou (mieux) en utilisant le SDK Javascript de l’application (approche orientée objet).

Toutes les informations concernant l’API.

API Je Lève La Main

Que peut-on faire avec l’API ?

Par exemple:

Extraire des ensembles d’utilisateurs vérifiant certaines conditions (membres de groupes, participants à une session…)
Extraire des ensembles de questions (quizz) vérifiant certaines conditions (date de création, auteur…)
Calculer sur les ensembles extraits des données statistiques (nombre de bonnes réponses, centiles, moyennes…). Les résultats peuvent être détaillés (résultats par utilisateur) ou agrégés (moyennes, note maximale par quiz…).

Comme les ensembles retournés par l’API peuvent être arbitrairement grands et concerner des millions de données ou d’utilisateurs, ils sont retournés sous forme de pages contenant un nombre limité de données. Les ensembles calculés par l’API peuvent être combinés selon des règles booléennes (union, intersection…) quelle que soit la nature des objets contenus dans les ensembles (utilisateurs, quizz, résultats…).

l’API vous permet aussi d’insérer des données (par exemple des quiz) dans l’application. Ainsi, elle peut être utilisée pour bâtir un “exportateur” Moodle, permettant d’exporter vos quiz Moodle dans “Je Lève La Main”

La page de documentation détaille l’ensemble des requêtes disponibles et vous les met à disposition via une interface interactive qui vous permet de tester l’ensemble du langage sur les données réelles contenues dans l’application.

Une clé est nécessaire pour soumettre des requêtes à l’API à partir de votre serveur ou de vos applications. Le gestionnaire de clés vous permet de voir, ajouter et supprimer des clés. Vous devez être loggé pour y accéder (bouton “Login” en haut à droite de la page).

Si votre application manipule des données privées, un jeton d’accès additionnel vous sera demandé. Voir le paragraphe authentification pour plus de détails.

Un cas réel d’utilisation

La partie “graphe et statistiques” de l’application actuelle “Je lève La Main” est construite avec l’API, selon les méthodes décrites ci-dessus.

Imaginons par exemple la session n° 71330434 comprenant 30 participants et dans laquelle 2 quiz ont été joués.

Dans le module graphique, un utilisateur demande à construire l’histogramme du nombre moyen de bonnes réponses et obtient le graphique ci-dessous.

Ces données ont été obtenues en envoyant seulement 3 requêtes à l’API.

Requête n°1: Le module graphique envoie une requête de type getUserSet à l’API pour extraire la liste des particpants de la session n°71330434 :

GET https://api.jelevelamain.fr/getUserSet?sessionId=71330434&apiKey=API_KEY&accessToken=ACCESS_TOKEN

(API_KEY est la clé de l'API de l'application "module graphique" et ACCESS_TOKEN le jeton daccès de l’utilisateur loggé).

En réponse, l’API envoie la première page d’un ensemble d’utilisateurs identifié ci-dessous par tLVJ87xTktKONNdG4TVw-g :

{
    "dataSetId" : "tLVJ87xTktKONNdG4TVw-g",
    "itemType" : "user",
    "numberOfPages" : 1,    
    "numberOfItemsPerPage" : 50,   
    "totalNumberOfItems" : 30,
    "items" : User[], 
    "currentPageIndex" : 1 
}

Requête n°2: Le module graphique envoie une requête getQuizSet à l’API pour retrouver les quiz joués dans la session n°71330434 :

GET https://api.jelevelamain.fr/getQuizSet?sessionId=71330434&apiKey=API_KEY&accessToken=ACCESS_TOKEN

En réponse, l’API envoie la première page d’un ensemble de quiz identifié ci-dessous par vQc6eAvCbNClWxfUUbc0Tg :

{
    "dataSetId" : "vQc6eAvCbNClWxfUUbc0Tg",
    "itemType" : "quiz",
    "numberOfPages" : 1,    
    "numberOfItemsPerPage" : 50,   
    "totalNumberOfItems" : 2,
    "items" : Quiz[], 
    "currentPageIndex" : 1 
}

Requête n°3: Le module graphique envoie une requête getResults à l’API pour extraire le nombre moyen de bonnes réponses de chaque utilisateur membre du groupe tLVJ87xTktKONNdG4TVw-g pour les quiz du groupe vQc6eAvCbNClWxfUUbc0Tg :

GET https://api.jelevelamain.fr/getResults?sessionId=71330434&userSetId=DkkSL7fpfzqS-3dlosI66A&quizSetId=vQc6eAvCbNClWxfUUbc0Tg&sessionIds=71330434
&resultTypes=nbGoodAnswers&includeQuizzes=answered&aggregationFunctions=average&groupBy=user &apiKey=API_KEY&accessToken=ACCESS_TOKEN

{
    "dataSetId" : "tLVJ87xTktKONNdG4TVw-g",
    "itemType" : "computedResult",
    "numberOfPages" : 1,    
    "numberOfItemsPerPage" : 50,   
    "totalNumberOfItems" : 30,
    "items" : ComputedResult[], 
    "currentPageIndex" : 1 
}