ORCID API in Action (A. Wrigley)

orcid.orgorcid.orgContact Info: p. +1-301-500-2139 a. 10411 Motor City Drive, Suite 750, Bethesda, MD 20817 USA

Alainna Wrigley, ORCID Community Engagement & Support (APAC)

[email protected] | orcid.org/0000-0002-6036-0903

ORCID API in actionSingapore Management University

6 April 2016

http://orcid.org/0000-0002-6036-0903

orcid.org 2

The other stuff that has to happen

• Communications

• Rollout timing

• Encouraging use

...can be much harder & more time consuming than using the API

Let’s not get ahead of ourselves...

PHOTO: 3/2 nuts © M.G. Kafkashttps://flic.kr/p/4XytpS

orcid.org 3

• PLANPlan how the integration will work

• BUILDBuild and test your integration

• COMMUNICATEDesign & build connection points

Integrating in 3 steps

orcid.org 4

• PLAN: Plan how the integration will workUse the Collect & Connect use cases as a guide

PLAN your integration

iDs in publications (works)

iDs in peer review

iDs in funding

iDs for faculty/research staff

iDs and identity

orcid.org 5

Sector contributions

PHOTO: Stairway to somewhere © Jonathan Fenton tps://flic.kr/p/7Guxgu

COLLECT iDs PUBLISH on your site POST to record

Funders At grant application & review With award Grant award IDs

Research institutions

For new staff & students; at thesis submission

With works; in faculty profiles

Affiliation ID for institution

Publishers & repositories

For authors, contributors, reviewers With works Paper, dataset and

review IDs

Associations For members, authors, meeting participants With member profiles

Affiliation ID with association, work IDs for publications

Connecting to the ORCID registry

orcid.org

Two models:

1. Connect via a vendor system• Manuscript submission/publication• Document/data repositories• Profile systems• CRIS systems

2. Develop a custom connection

PHOTO: Stairway to somewhere © Jonathan Fenton https://flic.kr/p/7Guxgu

Custom integrations

orcid.org

Via the ORCID APIs

• Fine-tuned control and permissions• Customized buttons, user flows, & user feedback

Current integration list: http://members.orcid.org/current-integrations


orcid.org 8

API Features

Public API• Freely available to

anyone• API credentials belong

to the individual; are not transferrable

• Authenticate: Get a user’s authenticated ORCID iD• Read (Public): Search/retrieve public data• Create Records: via an on-demand process• Support: Public documentation and API users group –

no dedicated supportMember API• ORCID member

organizations• API credentials belong

to the organization• (Sandbox test

environment freely available to anyone)

All of Public API features, plus• Read (Limited): Search/retrieve limited-access data• Add: Post new items to a record• Update: Edit or delete items you previously added• Support: ORCID Support and training; office hours• Webhook record update notifications (Premium) • Monthly reporting & public data access (Premium)

Comparing Public & Member APIs

Selected vendor system connections

orcid.org

Publishing• eJournal Press• Editorial Manager• ScholarOne

Document / data repositories• Australian National Data System• dSpace• Europe PubMed Central

Profile systems• Loop• ResearcherID• Vivo

CRIS Systems• Converis• Pure• Elements

http://members.orcid.org/orcid-enabled-systems


Vendor systems: Elements

May 1, 2023 orcid.org 10

• Researchers follow a link to connect their records

• Elements reads the ORCID record and updates the Elements publication list

http://symplectic.co.uk/elements-updates/elements-integrates-with-orcid/

Vendor systems: Pure


• Pure helps create a new record for researchers who don’t have an ORCID iD

• Researchers who have an ORCID iD can search for it to enter in Pure

https://www.elsevier.com/solutions/pure/releases/pure-4.18

Vendor systems: Converis


• Converis helps create a new record for researchers who don’t have an ORCID iD

• Researchers can also sync their Converis and ORCID records

http://converis.thomsonreuters.com

Vendor systems: DSpace


• Only on DSpace 5+• Uses the Public API to look up

ORCID iDs• Offers matching tool to select

iDs of contributors from a list

https://wiki.duraspace.org/display/DSDOC5x/ORCID+Integration

orcid.org 14

• BUILD: Build and test your integration• Build & test the OAuth flow

• Register for sandbox credentials• Determine what permissions you’ll

need• Build & test information exchange

• Format data to and from your system• Test on the sandbox

BUILD your integration

orcid.org 15

API (Application Programming Interface): interface that lets one software program “talk” with another, exchanging data behind the scenes.

An ad, but good basic info about what an API can do:http://paidpost.nytimes.com/ca-technologies/apis-the-building-blocks-of-the-app-economy.html

What is an API?


orcid.org 16

• Permissions / scopes: your contract with the user

• The ORCID messages: format of the data exchanged

• OAuth calls: the permission protocol – how you “execute the contract”

• ORCID-specific calls: providing & receiving information with the registry

The ORCID API


orcid.org

Basic API flow

ORCID Record

Yes!Do you have permission to do what you want to do?

Get the permission; store iD and “token”

Read the record or update the record

No

OAuth

PHOTO: electronic circuit boardwww.flickr.com/photos/creative_stock/5227842611

Explaining scopes / permissions

orcid.org

ORCID registry depends on user-based permissions: Can I...• have your iD (/authenticate)

• read your ORCID record (/read-public)

• interact with the activities on your record(/activities/update)

• update your biographical information(/orcid-bio/update)

What a message looks like

orcid.org

orcid.org 20

• COMMUNICATE: Design & build connection points• Use ORCID guidelines• Permission/sign-in button• Authorize confirmation page• Deny reconsider page• Custom data exchange pages (if needed)• (plus more direct communication with researchers)

COMMUNICATE your integration


OAuth in three easy steps

orcid.org

OAuth is a standard protocol used to obtain user permission to interact with their ORCID record


Step 1: Initiate the process

orcid.org

Initiate the process: Send the user to a “fancy” URLhttps://sandbox.orcid.org/oauth/authorize? \client_id=APP-XT8FBKJRO3MR8WDR& \response_type=code& \scope=/orcid-profile/read-limited%20/activities/update& \redirect_uri=https://my.URL.org& \ family_names=Researcher&given_names=Bob&[email protected]

base URL – displays the screen

who’s asking?what permissions?

where the user goes next

personalize theexperience


What the user sees

orcid.org

link from your website

custom email to researchers


What the user sees

orcid.org

sign-in form

registration form

already signed in


Step 2: Magic code & user feedback

orcid.org

ORCID sends the user to your redirect, with a codehttps://my.URL.org?htA3yE

you... • Save the code – you need it for the next step• Display useful feedback to the user

• Authorize: thanks for your permission!• Deny: sure you don’t want to give permission?

The magic code – it grants authorization!


Feedback

orcid.org

Examples from Crossref:

Authorized Denied

Step 3a: Transform the code into a token

orcid.org

Use the code to gain access using the ORCID APIhttps://api.sandbox.orcid.org/oauth/tokenHEADER: accept:application/jsonDATA: client_id=APP-XT8FBKJRO3MR8WDR client_secret=e285575c-4794-464b-a807-6f1c06b63grant_type=authorization_codecode=htA3yEredirect_uri=https%3A%2F%2Fmy.URL.org

PHOTO: Job Meetingwww.flickr.com/photos/jobmeeting/14375164286

our API calls always looks like URLs (RESTful)

what format?

the magic codeconfirming that you arethe right one to get thisinformation


Step 3b: Store the result

orcid.org

The result of the call"access_token" :"6710dfee-6aab-445b-a266-205dd9085273","token_type" : "bearer","expires_in" : 631138518,"scope" : "/orcid-profile/read-limited /activities/update","orcid" : "0000-0001-6356-0580","name" : "Bob Researcher"

store the access token and iD

when permission expires (in seconds – 20 yrs)your permission – the executed contract

iD & name for the person who gave permission

what you can do


Action Permission required CallRead the ORCID record: Search/retrieve public and limited-access data (depends on researcher-set data visibility)

• /orcid-profile/read-limited GET

Add research activities: Attach new items to a person’s ORCID iD, such as works, peer review, affiliations, funding

• /activities/update PUT

Add person info: Include new information about the person, such as alternate names, keywords, websites, alternate person identifiers, etc.

• /orcid-bio/update PUT

Update: Edit or delete items and information that you previously added

• /activities/update POST

What can you do with the permission?


An example: get data from the record

orcid.org

HTTP Method: GET

URL: https://api.sandbox.orcid.org/v1.2/0000-0000-0000-0000/orcid-profile

HEADERS: accept:application/json Authorization: Bearer 6710dfee-6aab-445b-a266-205dd9085273

iD and access tokenfrom OAuth calls


An example: add data to the record

orcid.org

HTTP Method: PUT

URL: https://api.sandbox.orcid.org/v1.2/0000-0000-0000-0000/orcid-works

HEADERS: content-type:application/vnd.orcid+xmlAuthorization: Bearer 6710dfee-6aab-445b-a266-205dd9085273

DATA: the file location=@file_location_name

iD and access tokenfrom OAuth calls

PHOTO: London, Englandhttps://flic.kr/p/qhALa3 orcid.org 32

1. Show us how the integration works2. Request production API credentials

from ORCID3. Take the application live4. Let everyone know!

Once it’s ready, take it live

Resources


API documentationhttp://members.orcid.org/api

List of supported vendor systems (includes details on how to connect)http://members.orcid.org/orcid-enabled-systems

List of current integrationshttp://members.orcid.org/current-integrations

Tutorial: ORCID API (Searches, OAuth, Create on Demand)http://is.gd/VALA2016ORCID

ORCID API User Listservhttp://groups.google.com/group/orcid-api-users

ORCID API Source (Github)https://github.com/ORCID/ORCID-Source/blob/master/orcid-model/src/main/resources/README.md

•

•

•

•

•

•

Date post:	25-Jan-2017
Category:	Education
Upload:	orcid-inc
View:	307 times
Download:	2 times

ORCID API in Action (A. Wrigley)

Education