ORCID propose plusieurs API qui permettent à vos systèmes de se connecter au ORCID registre, y compris la lecture et l'écriture dans ORCID enregistrements. Certaines fonctions de l'API sont librement accessibles à tous (API publique); d'autres ne sont disponibles que pour ORCID organisations membres (API membre et membre Premium). Tout le monde est libre de tester n'importe laquelle de nos API sur notre serveur de test sandbox.
Avant de commencer
Lorsque vous commencez à planifier votre intégration, vous devez considérer :
- Ce que vous voulez faire avec le ORCID API— veuillez visiter notre workflows.
- Que votre organisation soit déjà un ORCID membre ou est envisageant de devenir un. Seulement ORCID les membres peuvent ajouter des éléments à ORCID Records.
- Que vous utilisiez un système qui prend déjà en charge ORCID. Si c'est le cas, cela peut être aussi simple que de configurer votre système pour qu'il fonctionne avec ORCID.
- Comment vous communiquerez avec vos chercheurs au sujet des changements mis en œuvre, de ce dont vous aurez besoin de leur part, des avantages pour eux et de ce qu'ils devront faire. Visitez notre Ressources de sensibilisation page pour des idées sur la façon de créer une campagne de communication autour de votre nouvelle intégration.
Inscrivez-vous pour obtenir les informations d'identification du bac à sable et créez un test ORCID iD
Nous vous demandons de créer d'abord des outils qui interagissent avec le ORCID tas de sable pour éviter d'affecter les données du registre de production pendant les tests, ou vos propres systèmes.
Vous pouvez demander les informations d'identification de l'API du membre du sandbox pour créer et tester votre application. Ces informations d'identification vous permettent d'effectuer des appels à l'API du membre sandbox pour lire, écrire et mettre à jour ORCID records. L'accès à l'environnement de test du bac à sable est librement accessible à tous, même si vous n'êtes pas ORCID organisation membre.
Notes: Si vous utilisez un système tiers prenant déjà en charge ORCID, vous n'aurez peut-être pas besoin de vous inscrire pour obtenir les informations d'identification de l'API sandbox.
Le bac à sable vous permet de créer des comptes utilisateurs de test et de développer votre intégration sans avoir à vous soucier d'affecter les données en direct (production) ORCID Enregistrement. Le bac à sable se comporte de la même manière que la production ORCID Registre avec quelques exceptions.
Créer un compte de test
Afin de tester le ORCID API et appels d'API, tels que la lecture et l'ajout d'informations à un ORCID record, vous devrez également créer un test ORCID enregistrer dans le bac à sable. Cela peut être fait via l'interface utilisateur, un peu comme sur la production ORCID Enregistrement. Aller à https://sandbox.orcid.org/register et inscrivez-vous pour un compte.
Adresses e-mail des expéditeurs
Le serveur sandbox envoie des e-mails de notification uniquement à Mailinator (@mailinator.com) afin de ne pas spammer involontairement les serveurs de messagerie. Vous ne recevrez pas d'e-mail de vérification ni de notification de réinitialisation du mot de passe, sauf si vous utilisez une adresse @mailinator.com, et une vérification est nécessaire pour apporter des modifications manuelles aux enregistrements de bac à sable. En savoir plus sur leurs boîtes de réception publiques gratuites ici. Si vous ne souhaitez pas utiliser un Mailinator adresse, veuillez noter votre nom d'utilisateur et votre mot de passe (car vous les utiliserez pour autoriser votre application lors des tests), et contactez-nous pour demander de l'aide pour la vérification.
Mailinator est un service de messagerie qui dispose d'un service public gratuit et d'un service privé payant. Pour tester, vous pouvez utiliser le service public entièrement gratuit. En savoir plus sur leurs niveaux ici.
Mailinator est un service tiers qui n'est ni géré ni maintenu par ORCID. Nous vous recommandons d'examiner le fonctionnement de ce service et ses limites avant d'utiliser ces adresses.
Déterminez les autorisations utilisateur dont vous aurez besoin
Le ORCID L'API des membres peut être utilisée pour lire, ajouter ou mettre à jour des informations sur le compte d'un utilisateur. ORCID enregistrement—il vous suffit de demander la permission à vos chercheurs. Les étendues dont vous avez besoin affecteront largement l'API qui convient le mieux à votre système.
Lorsque vous demandez l'autorisation d'interagir avec un ORCID l'enregistrement de l'utilisateur, vous spécifiez une ou plusieurs « étendues ». Chaque étendue vous permet de faire certaines choses, comme lire l'enregistrement ou mettre à jour une section particulière.
3 patte désigne les trois acteurs impliqués dans l'obtention de l'autorisation d'un utilisateur ; ORCID, votre système et l'utilisateur lui-même.
/authentifier 
Ce périmètre est utilisé pour collecter les ORCID iD et lire les informations publiques sur le dossier uniquement. Toutes les autres étendues à 3 branches incluent l'autorisation d'authentification, cette étendue peut donc être omise si vous demandez un autre accès. Cette portée est disponible sur l'API membre ou publique.
/read-limited (API membre uniquement) 
Cette étendue est utilisée pour accéder à la lecture des éléments publics et à visibilité limitée sur un ORCID enregistrer. Ce champ d'application n'est disponible que sur l'API Member.
/activities/update (API membre uniquement) 
Cette portée est utilisée pour écrire, mettre à jour et supprimer des éléments dans les sections affiliation, financement, travaux et recherches et les sections d'évaluation par les pairs d'un ORCID enregistrer. Ce champ d'application n'est disponible que sur l'API Member.
/person/update (API membre uniquement) 
Cette portée est utilisée pour écrire, mettre à jour et supprimer des éléments dans les sections autres noms, mots-clés, pays, URL de recherche, sites Web et identifiants externes personnels de l'enregistrement. Ce champ d'application n'est disponible que sur l'API Member.
ouvert
Cette portée est utilisée par les intégrateurs OpenID lorsqu'un id_token est requis. Lorsque la portée openid est incluse, le registre renvoie un id_token dans la réponse du jeton et accorde au client l'autorisation d'accéder au point de terminaison des informations utilisateur pour cet utilisateur. Cette portée est disponible sur l'API publique et membre.
Veuillez noter que la portée 'openid' ne commence pas par un '/' comme les autres ORCID Portées de l'API. Ceci est dû au fait que la portée 'openid' n'est pas définie par ORCID, mais défini à la place par la spécification OpenID Connect. Veuillez consulter notre Documentation OpenID pour plus d'information.
Portées multiples
Plusieurs étendues peuvent être demandées en une seule interaction en répertoriant les étendues dans l'URL d'authentification avec un espace encodé entre chacune, comme scope=/read-limited%20/activities/update%20/person/update
Accès complet
Si vous souhaitez un accès complet pour lire et modifier un enregistrement, incluez trois étendues dans votre URL d'authentification : /read-limited, /activities/update et /person/update. Dans l'URL, ils apparaîtraient sous la forme scope=/read-limited%20/activities/update%20/person/update
Portées à deux branches (informations d'identification client)
Pour certaines activités, vous n'avez pas besoin de demander la permission à l'utilisateur. Les champs d'application OAuth à deux branches sont demandés directement à partir du ORCID API et ne nécessitent pas l'autorisation du chercheur. Les tokens avec ces portées sont valables 20 ans et peuvent être réutilisés
/ read-public
Cette portée est utilisée pour lire des informations publiques sur un seul ORCID iD ou rechercher ORCID enregistrements. Cette portée est disponible sur l'API membre ou publique.
/ webhook
Cette étendue permet à une application cliente d'enregistrer un webhook sur un ORCID enregistrement, afin de recevoir des notifications lorsqu'un enregistrement est mis à jour. Cette portée est disponible pour premium ORCID membres seulement. Si vous n'êtes pas membre premium, mais que vous souhaitez tester cette fonction dans le Developer's Sandbox, veuillez contact ORCID Community.
- Autrefois ORCID pris en charge d'autres champs d'application, qui ont maintenant été abandonné.
- Vous pouvez trouver quelles étendues sont nécessaires pour ajouter ou mettre à jour une section particulière ici.
Assurez-vous que vous pouvez stocker les données en toute sécurité
Il est important que votre système puisse stocker des informations de manière sécurisée.
Les intégrations doivent stocker plus que juste ORCID enregistrements. Votre système devra être capable de :
- Accepter et stocker ORCID iDs : votre système devra connaître les iD de ORCID enregistrement à mettre à jour. Stockez-le avec les informations du chercheur. Notre recommandation est de stocker l'URI https complet : https://orcid.org/0000-0001-5727-2427.
- Accepter et stocker persistant jetons d'accès et rafraîchir les jetons: les jetons d'accès peuvent être utilisés pour lire et mettre à jour les enregistrements, ainsi que pour indiquer que le iD a été authentifié. Les jetons persistants sont valides pendant environ 20 ans ou jusqu'à ce que l'utilisateur les révoque. Les jetons d'actualisation peuvent être utilisés pour créer de nouveaux jetons d'accès avec des étendues identiques ou limitées. Stockez les jetons avec les informations du chercheur. Nous vous recommandons également de ranger le portée du jeton, et le,expiration du jeton.
- Accepter et stocker mettre des codes (si mise à jour ORCID enregistrements) : chaque élément que vous ajoutez au ORCID Le registre sera renvoyé avec un code put par le ORCID API. Enregistrez ce code de mise avec l'élément dans votre système‚ c'est ainsi que vous identifierez quel élément doit être lu ou mis à jour.
- Consigner les interactions : votre système doit enregistrer les deux appels passés au ORCID API et réponses reçues. C'est nécessaire donc ORCID peut aider si un problème survient plus tard.
- Fournissez des messages d'erreur et un contact d'assistance lorsqu'une interaction ne se déroule pas comme prévu.
Renseignez-vous auprès du ORCID équipe pour démontrer le fonctionnement de votre application
Avant que votre intégration ne puisse être mise en ligne sur le ORCID registre de production, notre équipe d'engagement vérifiera que tout ce que vous avez construit sur le bac à sable fonctionnera également en production. Si vous utilisez un système avec ORCID support, cette étape peut être sautée.
Demande des organisations membres ORCID Identifiants API des membres sur le serveur de production (en direct) en remplissant le Formulaire de candidature client API de membre de production. Avant d'émettre des informations d'identification de l'API de membre de production, le ORCID L'équipe d'engagement examinera une démonstration de votre intégration dans le ORCID bac à sable. Cela nous donne une chance de voir les excellentes intégrations que vous avez créées et d'offrir des améliorations de flux de travail, ainsi que de vérifier que toutes les intégrations répondent à nos meilleures pratiques.
Pour fournir une démonstration de votre système, vous devrez configurer une intégration fonctionnelle avec le ORCID bac à sable que le ORCID l'équipe peut prévisualiser. Il existe plusieurs façons de partager votre intégration de sandbox fonctionnelle :
- Recommandée: Démo en direct: Contactez-nous pour planifier une démonstration en direct. Nous fournirons un logiciel de réunion qui vous permettra de partager votre écran pour vous permettre de faire une démonstration de votre intégration. Cela nous donne également l'occasion d'en savoir plus sur le fonctionnement de votre système et sur la façon dont vous expliquez les avantages de votre ORCID l'intégration, afin que nous puissions fournir un meilleur support pour vous et vos utilisateurs.
- Site de test: Si votre site de développement est public, envoyez-nous l'URL ainsi que des informations d'identification de test (si nécessaire) pour accéder à votre système et des instructions décrivant comment utiliser les ORCID fonctionnalités. Fournissez une documentation supplémentaire pour vérifier ce que nous ne serions pas en mesure de voir du côté utilisateur, par exemple la version de l'API utilisée, les données stockées par votre système, etc.
- Screencast ou captures d'écran (recommandé pour ORCID-systèmes activés qui nécessitent une démonstration) : Envoyer un enregistrement ou un ensemble de captures d'écran avec des descriptions expliquant et démontrant clairement comment votre intégration fonctionne à chaque étape, y compris ce qui se passe si un utilisateur refuse l'accès ou déconnecte son iD. Assurez-vous de fournir une documentation supplémentaire pour vérifier tout ce que nous ne pourrions pas voir du côté de l'utilisateur, comme la version de l'API utilisée et la manière dont les données sont stockées.¬¨‚
Si vous utilisez l'un des ORCID-systèmes activés qui ne nécessitent pas de démonstration, vous pouvez directement demander les informations d'identification de l'API de membre de production. Assurez-vous de spécifier le système (et, le cas échéant, la version) que vous utilisez dans les notes.
Il y a un certain nombre d'exigences que nous attendons de toutes les intégrations de membres. le ORCID L'équipe s'assurera que ces exigences ont été respectées dans le cadre du processus d'examen de l'intégration.
- Utilisez OAuth s'authentifier ORCID ID (ne pas autoriser les utilisateurs à rechercher ou à saisir ORCID ID.)
- Inclure un ORCID bouton ou lien de marque sur votre site pour initier l'authentification de l'iD.
- Présentez l'écran d'autorisation OAuth selon notre lignes directrices
- Utilisez HTTPS pour les URI de redirection de votre site et sur ORCID Appels API
- Acceptez et stockez toutes les données renvoyées dans l'échange de jetons avec les données de l'utilisateur dans votre système
- Utiliser le bon portée et méthodes de demande (par exemple, les appels POST pour ajouter de nouvelles informations et les appels PUT pour mettre à jour les informations existantes)
- Afficher publiquement les authentifiés ORCID identifiants. Les identifiants doivent être affichés à la suite de notre marque et iD afficher les lignes directrices.
Demander des identifiants sur le serveur de production
Vous pouvez demander des informations d'identification API de membre une fois que votre intégration a été examinée par le ORCID équipe ou si vous utilisez un système de fournisseur de services doté d'un ORCID l'intégration.
Vous devrez remplir le formulaire pour enregistrer une demande client. Voici un aperçu rapide des champs demandés:
Notes pour ORCID D'USINE: Utilisez ce champ pour laisser ORCID savoir si vous utilisez un système de fournisseur, si les intégrations ont été examinées, etc.
Adresse email de contact: Nous enverrons les informations d'identification à cette adresse. Il doit s'agir du contact avec lequel nous avons travaillé sur l'intégration ou du contact technique que nous détenons pour votre organisation.
Contact pour recevoir le code PIN pour accéder aux informations d'identification: Nous vous envoyons les informations d'identification complètes de manière sécurisée. Nous enverrons un mot de passe pour accéder à vos informations d'identification API à ce contact. Il doit s'agir d'un contact différent du contact précédent répertorié.
Brève description de votre application client: Ce texte sera affiché sur l'écran d'autorisation avec une icône de point d'interrogation pour les utilisateurs de votre intégration. Une brève description de votre intégration est requise.
URL de la page d'accueil de votre application: Affiché sous forme de lien sur la liste des organisations de confiance au sein des utilisateurs ORCID la page des parties de confiance. Cela devrait être un lien vers votre organisation ou la page principale de votre application.
URI de redirection OAuth2 ou URL de rappel pour le client : URL autorisées dans votre application Web vers lesquelles les utilisateurs seront renvoyés après avoir autorisé l'accès à leur ORCID enregistrer des données. Tous les URI de redirection doivent être HTTPS pour les clients de serveur de production (en direct).
Une fois que vous avez fait votre demande, un processus manuel se produit pour vous délivrer des informations d'identification et vous recevrez un e-mail avec votre client iD et secret client. Généralement, ces demandes sont traitées en moins de 48 heures.
Transférez votre candidature au ORCID Registre de production
Une fois que vous avez vos informations d'identification, vous êtes prêt à les mettre en ligne. Si vous souhaitez tester votre intégration avant son lancement public, veuillez utiliser les propres ORCID dossier ou celui d'un collègue ORCID record.
Lancez et informez tout le monde
La mise en ligne d'une application n'est pas la dernière étape : vous devez continuer à communiquer avec vos utilisateurs pour qu'ils sachent comment connecter leurs ORCID iD à votre système rapidement et facilement. Les intégrations efficaces contiennent à la fois une composante technique (que ce guide couvre) ainsi qu'une composante sociale. Les chercheurs doivent être informés de ce que ORCID est, pourquoi vous demandez l'accès à leur ORCID enregistrer et ce que vous ferez de leurs données.
- Créez un calendrier de communication : assurez-vous que les parties prenantes sont au courant de votre ORCID projet bien avant de vous lancer.
- Utilisez une combinaison de communications descendantes et ascendantes.
- Promouvoir votre ORCID l'intégration souvent et à des publics différents.
- Créer des ressources locales pour soutenir vos utilisateurs, tels que des FAQ, des guides de bibliothèque, des pages Web, des didacticiels et des vidéos.
- Nommer une personne de contact locale pour ORCID-questions connexes.
Pour soutenir la composante sociale, nous proposons une boîte à outils de Ressources de sensibilisation pour vous aider à développer une campagne pour soutenir votre intégration et communiquer à vos chercheurs:
- Quoi ORCID est.
- Pourquoi votre système collecte les identifiants et comment votre système effectuera des tâches, telles que la mise à jour de leurs enregistrements.
- Pourquoi vos chercheurs bénéficieront-ils de la création d'un ORCID iD et connecter leurs identifiants à votre système.
- Comment ORCID profite à la communauté de recherche mondiale au sens large.
Nous construirons continuellement cette «bibliothèque» de ressources sur la base des commentaires de la communauté. Si vous avez une idée de quelque chose que vous aimeriez voir, n'hésitez pas à nous contacter.