Espace API ORCID : en pratique
Obtenir un laisser-passer
Pour utiliser l’API ORCID, il est nécessaire d’obtenir un laisser-passer (credentials) délivré par ORCID. Celui-ci consiste en un couple d’informations (Client ID et Client Secret) qu’il convient d’entrer en paramètres lors des appels à l’API ORCID.
Le laisser-passer (credentials) est nécessaire à plusieurs niveaux :
- pour utiliser l’API publique : si votre établissement n’est pas membre du consortium ORCID France, il convient de disposer d’un compte ORCID et d’avoir demandé, via ce dernier, un laisser-passer qui sera lié à votre compte ORCID et ne pourra pas être transféré à une autre personne.
- pour activer l’utilisation de l’API membre : si votre établissement est membre du consortium ORCID France, l’obtention d’un laisser-passer implique de renseigner un formulaire indiquant un souhait de connexion entre ORCID et une application tierce (client application) correspondant à un projet d’usage précis au sein de votre établissement. Les informations concernant l’application et l’usage associé restent cependant assez basiques à ce stade :
- une adresse e-mail de contact
- une brève description de votre application cliente
- l’URL de la page d’accueil de votre application
- l’URI de redirection OAuth2 ou URL de rappel pour le client
- d’éventuelles remarques pour les équipes ORCID (champ utilisé pour informer ORCID si vous utilisez un système fournisseur ou si les intégrations ont été examinées)
- pour tester l’API membre : si votre établissement n’est pas membre du consortium ORCID France, il convient de renseigner le même formulaire que celui demandé aux établissements membres pour la déclaration de leur application.
A l’issue de chacune de ces étapes, ORCID envoie un e-mail crypté comportant votre Client ID et votre Client Secret, informations à ne surtout pas diffuser.
Utiliser l'API publique
L’API ORCID publique permet deux types d’usage :
- la collecte des identifiants ORCID authentifiés (sous réserve d’obtention du laisser-passer).
- la consultation des données publiques du registre ORCID.
L’API publique est simple à prendre en main et ne nécessite aucun pré-requis. Un navigateur suffit pour lancer différentes requêtes sur les données du registre ORCID. Construites à partir de la syntaxe de recherche SolR, les requêtes renvoient des fichiers XML ou CSV. Les champs affichés dans la réponse sont paramétrables. Le nombre de résultats est automatiquement tronqué à 1 000.
Consulter la liste des champs interrogeables
Les carences dans le contenu du registre ORCID
Attention : l’API publique ne présente que les données publiques du registre ORCID, y compris avec leurs carences et les biais induits par leur mode de production principale (saisie manuelle et facultative par le chercheur).
Les doublons : pour créer un compte ORCID, il suffit de renseigner un nom, un prénom et une adresse mail. En théorie, un chercheur est supposé n’avoir qu’un seul compte ORCID. En pratique, il peut avoir autant de comptes que d’adresses mail.
Les comptes vides : Pour créer un compte ORCID, il suffit de renseigner un nom, un prénom et une adresse mail. Toutes les autres informations sont facultatives. À titre d’exemple, début juillet 2021, 27% des comptes disposent d’une information d’affiliation (« employment ») ; 27% des comptes disposent d’une information relative aux publications (« works »). (source : https://orcid.org/statistics )
Les informations obsolètes : l’immense majorité des comptes ORCID a été alimentée manuellement par les chercheurs, sur une base strictement déclarative. Si les informations renseignées étaient justes le jour de la création du compte, elles peuvent ne plus l’être.
Les conditions de fiabilisation des informations par l’institution du chercheur : la philosophie d’ORCID est que le chercheur est maitre des informations qui le concernent. Pour qu’un compte soit vérifié par une institution, il faut que les deux conditions suivantes soient réunies : le chercheur autorise l’institution à interagir avec son compte ; l’institution a développé une intégration de son système d’information avec ORCID. De fait, très peu de comptes sont aujourd’hui fiabilisés.
Tester l’API membre
à noter : il est possible d’utiliser l’environnement de test (« sand box ») sans être membre du consortium ORCID France
Dans des situations réelles, les interactions API sont générées par votre système à l’aide d’un langage de programmation (tel que PHP, Java ou Ruby on Rails). Cependant, pour la pratique et les tests, il est possible d’interagir avec les API ORCID à l’aide d’une gamme d’outils capables de créer et de recevoir des requêtes HTTP. Les outils suivants peuvent être utilisés : cURL, Postman, widget, hurl.it, Google OAuth 2.0 Playground, etc.
Tout au long du processus, l’équipe technique d’ORCID assure un service d’assistance.
Les étapes du processus de test
Demander un laisser-passer
Préparer l’environnement de test
- se créer un identifiant ORCID dans l’environnement de test
- compléter le formulaire : attention à ne pas utiliser une adresse mail réelle, celle utilisée doit impérativement se terminer par @mailinator.com
- créer ensuite votre mot de passe associé à cet identifiant ORCID
- paramétrer la visibilité des informations présentes dans le compte ORCID. Dans la messagerie : valider l’adresse mail pour terminer le processus de création de l’identifiant ORCID
- compléter manuellement le compte ORCID (avec un pays, une affiliation, etc.)
Rassembler les identifiants ORCID
avec lesquels vous voulez interagir et définir les types d’interactions que vous voulez avoir avec ces comptes. Vous savez à qui vous devez demander quelles autorisations.
Implémenter le protocole OAuth 2.0
- demander les autorisations au chercheur
- récupérer le jeton d’accès (token) et le sauvegarder
Utiliser les méthodes de l’architecture REST
pour lire le contenu du compte ORCID, ajouter du contenu, modifier, ou effacer les informations que vous aurez envoyées, sous réserve d’autorisation du chercheur.
Définir les paramètres du système d’information ou de l’application tierce
- utiliser HTTPS pour les URI de redirection de votre site et pour les appels d’API ORCID
- enregistrer les appels passés à l’API ORCID et les réponses reçues
- accepter et stocker les identifiants ORCID.
- accepter et stocker les jetons d’accès persistants et les jetons d’actualisation. Ils peuvent être utilisés pour lire et mettre à jour des fiches, ainsi que pour indiquer que l’identifiant ORCID a été authentifié.
- utiliser des autorisations (scopes) et des méthodes de requêtes appropriées. Par exemple, les appels POST pour ajouter de nouvelles informations et les appels PUT pour mettre à jour les informations existantes
- accepter et stocker les put codes, en cas d’écriture et plus particulièrement de mise à jour des comptes ORCID ; chaque élément ajouté au compte ORCID sera retourné avec un put code par l’API ORCID.
- fournir des messages d’erreur lorsqu’une interaction ne se déroule pas comme prévu.
Dans le système d’information, paramétrer l’affichage des informations relatives à ORCID
- afficher les informations sur ORCID et son intégration dans le système
- ajouter un bouton permettant de lancer l’authentification de l’identifiant ORCID : en cliquant sur ce bouton, le chercheur liera son compte ORCID à votre système d’information. Le champ affichant l’identifiant ORCID dans votre système doit être en lecture seule pour ne pas être saisi par copier-coller mais bien renseigné à l’issue de ce processus d’authentification du compte
- afficher sur l’écran les autorisations du protocole OAuth conformément aux directives fournies
- ajouter l’icône ID à côté du nom du chercheur
Implémenter l’API membre
à noter : pour utiliser cette API en production, votre établissement doit être membre du consortium ORCID France. Chaque projet d’intégration étant différent, il est raisonnable d’envisager un délai de 6 mois entre la définition des besoins et sa mise en production effective.
Voici les différentes phases du processus d’intégration d’ORCID dans un système d’information ou une application tierce :
Définir le système à connecter à ORCID ainsi que les fonctionnalités souhaitées. L’exploitation de l’API membre n’a de sens que si elle s’inscrit dans un projet d’intégration avec une application tierce (ex : une archive ouverte, un entrepôt de données, un système-information-recherche…).
Informer l’Abes, coordonnateur du consortium ORCID France, du projet d’intégration.
Tester dans l’environnement de test (et passer par toutes les étapes de ces tests) pour vérifier que votre système dispose de l’architecture technique adéquate.
Mettre en place un service d’assistance pour gérer les éventuels dysfonctionnements.
Planifier une démonstration devant l’équipe technique d’ORCID : le passage en production sera soumis à une validation d’ORCID, pour s’assurer du respect des bonnes pratiques et envisager les mesures d’accompagnement à destination des chercheurs de votre institution.
