orcid api in action (a. wrigley)
TRANSCRIPT
![Page 1: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/1.jpg)
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
![Page 2: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/2.jpg)
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
![Page 3: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/3.jpg)
orcid.org 3
• PLANPlan how the integration will work
• BUILDBuild and test your integration
• COMMUNICATEDesign & build connection points
Integrating in 3 steps
![Page 4: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/4.jpg)
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
![Page 5: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/5.jpg)
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
![Page 6: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/6.jpg)
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
![Page 7: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/7.jpg)
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
PHOTO: Stairway to somewhere © Jonathan Fenton https://flic.kr/p/7Guxgu
![Page 8: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/8.jpg)
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
![Page 9: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/9.jpg)
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
PHOTO: Stairway to somewhere © Jonathan Fenton https://flic.kr/p/7Guxgu
![Page 10: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/10.jpg)
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/
![Page 11: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/11.jpg)
Vendor systems: Pure
May 1, 2023 orcid.org 11
• 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
![Page 12: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/12.jpg)
Vendor systems: Converis
May 1, 2023 orcid.org 12
• 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
![Page 13: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/13.jpg)
Vendor systems: DSpace
May 1, 2023 orcid.org 13
• 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
![Page 14: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/14.jpg)
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
![Page 15: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/15.jpg)
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?
PHOTO: 3/2 nuts © M.G. Kafkashttps://flic.kr/p/4XytpS
![Page 16: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/16.jpg)
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
PHOTO: 3/2 nuts © M.G. Kafkashttps://flic.kr/p/4XytpS
![Page 17: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/17.jpg)
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
![Page 18: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/18.jpg)
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)
![Page 19: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/19.jpg)
What a message looks like
orcid.org
![Page 20: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/20.jpg)
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
![Page 21: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/21.jpg)
PHOTO: electronic circuit boardwww.flickr.com/photos/creative_stock/5227842611
OAuth in three easy steps
orcid.org
OAuth is a standard protocol used to obtain user permission to interact with their ORCID record
![Page 22: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/22.jpg)
PHOTO: electronic circuit boardwww.flickr.com/photos/creative_stock/5227842611
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
![Page 23: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/23.jpg)
PHOTO: electronic circuit boardwww.flickr.com/photos/creative_stock/5227842611
What the user sees
orcid.org
link from your website
custom email to researchers
![Page 24: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/24.jpg)
PHOTO: electronic circuit boardwww.flickr.com/photos/creative_stock/5227842611
What the user sees
orcid.org
sign-in form
registration form
already signed in
![Page 25: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/25.jpg)
PHOTO: electronic circuit boardwww.flickr.com/photos/creative_stock/5227842611
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!
![Page 26: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/26.jpg)
PHOTO: electronic circuit boardwww.flickr.com/photos/creative_stock/5227842611
Feedback
orcid.org
Examples from Crossref:
Authorized Denied
![Page 27: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/27.jpg)
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
![Page 28: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/28.jpg)
PHOTO: electronic circuit boardwww.flickr.com/photos/creative_stock/5227842611
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
![Page 29: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/29.jpg)
May 1, 2023 orcid.org 29
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?
![Page 30: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/30.jpg)
PHOTO: electronic circuit boardwww.flickr.com/photos/creative_stock/5227842611
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
![Page 31: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/31.jpg)
PHOTO: electronic circuit boardwww.flickr.com/photos/creative_stock/5227842611
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
![Page 32: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/32.jpg)
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
![Page 33: ORCID API in Action (A. Wrigley)](https://reader034.vdocuments.net/reader034/viewer/2022042907/5888d8e31a28aba1058b6081/html5/thumbnails/33.jpg)
Resources
PHOTO: Stairway to somewhere © Jonathan Fenton https://flic.kr/p/7Guxgu
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
•
•
•
•
•
•