API REST

Labvanced propose une API REST permettant aux utilisateurs de récupérer des données depuis le serveur Labvanced, après que le(s) participant(s) ait (aient) terminé l'étude.

L'API REST est authentifiée par un jeton, qui vous permet de télécharger toutes vos données de manière programmatique. L'API REST est idéale pour les organisations et les institutions de recherche académique qui souhaitent centraliser leur récupération de données et stocker leurs données dans des endroits dédiés selon leur protocole de pipeline. Au lieu de sélectionner et de télécharger des données manuellement et de les enregistrer localement, cela permet aux organisations d'accéder aux données sur leurs serveurs, ce qui est également important pour le protocole GDPR.

La documentation (Swagger UI) des points de terminaison REST peut être trouvée ici : https://www.labvanced.com/openapi.html

Nous fournissons également une spécification openapi qui peut être utilisée pour générer automatiquement du code client pour différents langages de programmation (c'est-à-dire dans des outils comme Postman) : https://www.labvanced.com/labvanced-openapi.json

Création du jeton API

C'est une API sécurisée, ce qui signifie que vous devez valider l'accès à l'aide d'un jeton généré dans Labvanced afin d'accéder aux données.

Pour créer le jeton, connectez-vous à l'application Labvanced et allez dans l'onglet « Mon compte » situé sur le côté gauche du menu.

Il y a une section appelée « Identifiants API » et pour créer le jeton, il suffit de cliquer sur « Générer ».

indiquant le bouton qui génère l'API REST

Lorsque le jeton apparaît, double-cliquez sur la clé du jeton afin de tout sélectionner puis Ctrl+C pour le copier.

Avec ce jeton, vous pourrez accéder aux données de vos études et des sessions pertinentes.

Remarque : le jeton ne peut être généré que pour donner accès aux données de session par le propriétaire de l'étude.

Essayez-le en utilisant notre documentation API (Swagger UI)

Le moyen le plus simple d'essayer notre API est d'utiliser la fonctionnalité « Essayer » dans notre documentation API (Swagger UI) : https://www.labvanced.com/openapi.html

Dans le coin supérieur droit, cliquez sur « Autoriser ».

indiquant le bouton 'Autoriser' pour saisir l'API REST

Cela ouvrira une boîte de dialogue vous invitant à entrer / coller le jeton dans le champ « Valeur ».

Boîte de dialogue pour saisir les identifiants de l'API REST

Une fois que vous avez collé le jeton, cliquez sur « Autoriser », puis « Fermer » pour fermer la boîte de dialogue.

Remarque : Lorsque vous avez terminé de consulter les données, vous pouvez vous déconnecter de cette session en cliquant sur « Autoriser » situé dans le coin supérieur droit du site Web, puis, dans la boîte de dialogue qui apparaît, en cliquant sur le bouton « Déconnexion » qui apparaît dans le coin inférieur gauche.

Essayez d'accéder aux données via notre documentation API

Une fois connecté, vous pouvez utiliser ces deux zones pour accéder à vos données expérimentales :

Options de données de l'API REST pour accéder aux sessions et aux données des participants

  • /api/{expId}/download/{recSessionId} : cette section vous permet d'accéder et de télécharger les données d'un participant unique. Lorsque les données sont téléchargées, elles seront au format de fichier .csv selon la configuration que vous avez spécifiée dans les exportSettings trouvés sur la page « Vue des données et exportation » dans l'application Labvanced.
  • /api/{expId}/sessions : permet de récupérer toutes les sessions pour une expérience spécifique en entrant l'« id de l'expérience ».

Données de ‘/api/{expId}/sessions’

Il est préférable de commencer par le deuxième point de terminaison pour d'abord savoir quelles sessions d'enregistrement (et leurs rec_session_id correspondants) existent dans une expérience donnée. Cliquez sur le deuxième champ bleu étiqueté /api/{expId}/sessions et il s'ouvrira dans une vue plus grande, puis cliquez sur le bouton « Essayer » sur le côté droit :

Boîte de dialogue pour récupérer les données de l'expérience avec l'API REST basée sur l'id de session

En cliquant sur « Essayer », vous pourrez saisir des numéros dans le champ « expid » pour indiquer l'id de l'expérience pour laquelle vous souhaitez accéder aux données de session. Vous pouvez le trouver dans labvanced dans la page "Mes études" dans la colonne "ID". Une fois que vous avez rempli ce champ, cliquez sur « Exécuter ».

Une fois cela fait, vous pouvez faire défiler la page et voir les informations pour toutes les sessions dans cette expérience spécifique :

Exemple de données de session générées à l'aide de l'API REST

Veuillez noter l'un des rec_session_id dans le payload de réponse pour l'utiliser dans la section suivante afin de télécharger toutes les données enregistrées de cette session d'enregistrement.

Remarque : Pour saisir un « id d'expérience » différent, cliquez simplement sur le bouton rouge « Annuler » sur le côté droit, afin de pouvoir entrer un nouvel « id d'expérience ».

Données de ‘recSessionId’

Pour accéder et télécharger les données d'un participant, cliquez sur le premier champ bleu étiqueté /api/{expId}/download/{recSessionId} et il s'ouvrira dans une vue plus grande, puis cliquez sur le bouton « Essayer » sur le côté droit :

Dialogue pour spécifier l'id d'expérience et les numéros de session pour récupérer des données via l'API REST

En cliquant sur « Essayer », vous pourrez entrer des numéros dans les deux champs qui apparaissent en indiquant l'« id d'expérience » et le « rec_session_id » que vous souhaitez télécharger (voir la section précédente).

Une fois que vous avez saisi ces valeurs, il suffit de cliquer sur « Exécuter » et l'API sera exécutée. Ensuite, faites défiler la page, et vous verrez une option pour « Télécharger le fichier ».

Télécharger des fichiers générés par l'API REST

En cliquant sur « Télécharger le fichier », un .zip sera téléchargé contenant deux fichiers .csv, à savoir :

  • sessions.csv
  • trials.csv

Ces fichiers contiendront toutes les données pertinentes pour la session spécifique et les données d'essai associées.

Remarque : Pour récupérer une session différente, cliquez simplement sur le bouton rouge « Annuler » sur le côté droit, afin de pouvoir entrer un nouvel « id d'expérience » et un nouveau « rec_session_id » à télécharger.

En conclusion, ces étapes vous permettent d'accéder aux données à l'aide du jeton API que vous avez généré avec un jeton unique et sécurisé dans Labvanced afin de consulter les données expérimentales et de session.

Essayez-le avec Postman

C'est une deuxième option pour essayer l'API pour ceux qui utilisent déjà Postman (une plateforme API) dans leurs activités quotidiennes. Le jeton API Labvanced fonctionne également à partir de là.

Vous entrez l'URL dans le champ supérieur, basée sur le site Web de l'API Labvanced.

Ensuite, sélectionnez la clé et collez le jeton sous la colonne « valeur », comme montré ci-dessous :

Démonstration de l'utilisation de POSTMAN avec l'API REST générée par Labvanced

De cette façon, les données de session pour une expérience seront accessibles via Postman.

De même, vous pouvez suivre le même processus pour télécharger des fichiers pour un participant spécifique.

En procédant ainsi, l'aperçu affichera des caractères étranges, mais cela est normal car cette commande sert à récupérer des fichiers. Lorsque vous cliquez sur « Enregistrer les réponses » et « Enregistrer dans un fichier », les données pour le participant particulier apparaîtront normalement.

Démonstration de l'apparence des données basées sur des fichiers dans POSTMAN avec l'API REST de Labvanced