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)
support@orcid.org | orcid.org/0000-0002-6036-0903
ORCID API in action
Singapore Management University
6 April 2016

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. Kafkas
https://flic.kr/p/4XytpS

orcid.org 3
• PLAN
Plan how the integration will work
• BUILD
Build and test your integration
• COMMUNICATE
Design & build connection points
Integrating in 3 steps

orcid.org 4
• PLAN: Plan how the integration will work
Use 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
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 support
Member 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

Elements
12 April 2016 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/

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

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

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 board
www.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” URL
https://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=bobresearcher@mail
inator.com
base URL – displays the screen
who’s asking?
what permissions?
where the user goes next
personalize the
experience

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 code
https://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 API
https://api.sandbox.orcid.org/oauth/token
HEADER: accept:application/json
DATA:
client_id=APP-XT8FBKJRO3MR8WDR
client_secret=e285575c-4794-464b-a807-6f1c06b63
grant_type=authorization_code
code=htA3yE
redirect_uri=https%3A%2F%2Fmy.URL.org
PHOTO: Job Meeting
www.flickr.com/photos/jobmeeting/14375164286
our API calls always looks
like URLs (RESTful)
what format?
the magic code
confirming that you are
the right one to get this
information

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 Call
Read 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 token
from 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+xml
Authorization: Bearer 6710dfee-6aab-445b-a266-205dd9085273
DATA: the file location=@file_location_name
iD and access token
from OAuth calls

PHOTO: London, England
https://flic.kr/p/qhALa3 orcid.org 32
1. Show us how the integration works
2. Request production API credentials from
ORCID
3. Take the application live
4. Let everyone know!
Once it’s ready, take it live

Resources
PHOTO: Stairway to somewhere
© Jonathan Fenton https://flic.kr/p/7Guxgu
API documentation
http://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 integrations
http://members.orcid.org/current-integrations
Tutorial: ORCID API (Searches, OAuth, Create on Demand)
http://is.gd/VALA2016ORCID
ORCID API User Listserv
http://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
•
•
•
•
•
•

ORCID API in Action (A. Wrigley)

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Viewers also liked

Viewers also liked (16)

Similar to ORCID API in Action (A. Wrigley)

Similar to ORCID API in Action (A. Wrigley) (20)

More from ORCID, Inc

More from ORCID, Inc (20)

Recently uploaded

Recently uploaded (20)

ORCID API in Action (A. Wrigley)

Editor's Notes