Presentation at the 2016 ORCID South Africa Workshop (19 July 2016)

1. orcid.orgContact Info: p. +1-301-922-9062 a. 10411 Motor City Drive, Suite 750, Bethesda, MD 20817 USA
beyond what is ORCID…
...using the ORCID API
ORCID South Africa Workshop
19 July 2016
Matthew Buys
Regional Director, ORCID
m.buys@orcid.org
Twitter @mjbuys
http://orcid.org/0000-0001-7234-3684

2. 2
Organizations are
use ORCID APIs to
authenticate, collect,
display, and connect
persistent identifiers
for people, places,
and things in
research workflows
ORCID enables assertions

3. Some phrases
API - If your software gives my software one of these instructions
I’ve defined, it will perform this action, or return this
information.
OAuth2 - A standard set of rules which resource owners
(commonly users) to grant access to APIs SECURELY.
RESTful Service - A web API that implements a popular and
simple set of instructions in the same way as a whole bunch of
other web APIs do.
Persistent Identifier - An identifier that exists for a long long
long time and points at data. web APIs do.
Unique Identifier - Being the only one of its kind, a set of letters
and numbers that identifies one thing and only that thing.

4. What is an ORCID iD?
An ORCID iD is a unique persistent identifier
which resolves to data about a researcher.
Researchers control data associated with their
record.
It looks like this:
http://orcid.org/0000-0001-5727-2427

5. And returns things like this!
XML Data
JSON Data
HTML

6. What are the ORCID APIs?
Public API - Free and available to anyone
○ Authenticate
○ Read Public
Member API - Only available to member organizations
○ Read Limited (non-public information a researcher chooses
to share with a member organization)
○ Add and update records (requires users permission)
○ Webhooks
○ Researcher Notifications

7. What’s in a ORCID record?
Organized into two sections.
Person:
Names, Countries, Keywords,Websites, Person
Identifiers
Activities:
Education, Employment, Funding, Peer Reviews,
and Works

8. orcid.org 8
• 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 in a nutshell
PHOTO: 3/2 nuts © M.G. Kafkas
https://flic.kr/p/4XytpS

9. E N T E R O N C E
R E U S E O F T E N
INTEROPERABILITY
P U B L I S H E R
A S S E RT A U T H O R S H I P
E M P LOY E R
A S S E RT A F F I L I AT I O N
F U N D E R
A S S E RT AWA R D
C O N N E C TC O N
N
E C T
C O L L E C TC O L L E C T
C O L L E C T
R E S E A R C H E R
C O N N E C T
0 1 2 3 - 4 5 6 7 - 7 6 5 4 - 3 2 1 0
NIH Video
Wiley instructions
Publisher
requirement page
UC Davis LibGuide
SSO
Oxford LibGuide

10. 18 July 2016 orcid.org 10
DISPLAY
• In metadata
• On sites
• In publications
CONNECT
• Affiliations (employers)
• Works (publishers)
• Awards (funders)

11. orcid.org
Get permission, use permission
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

12. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
Get permission: API-edition
orcid.org
ORCID registry depends on user-based permissions:
Can I...
• have your iD (/authenticate)
• interact with the activities on your record
• read (/activities/read)
• update (/activities/update)
• interact with your biographical information
• read (/person/read)
• update (/person/update)

13. 18 July 2016 orcid.org 13
Part “0”:Authenticate

14. PHOTO: Job Meeting
www.flickr.com/photos/jobmeeting/14375164286
Involving the user
orcid.org
Key benefits:
• You know the user controls the iD
• User knows what’s going on/ user choice
• Privacy/ data control trends
• Position/ strengthen your system as a service
How?
• Just a “fancy” URL
• Prior iD not needed
• Hard things: promotion, finding touch points

15. PHOTO: Job Meeting
www.flickr.com/photos/jobmeeting/14375164286
Get permission: touch points
orcid.org
Look for natural fits:
• Your sign in – why not link your iD?
• Your account settings/ user profile
• Submission (of any type)
• Form fills: pre-fill from your Record!
• Registration: for conference or
meeting
• Reporting: Link your iD to get
started

16. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
The “fancy” URL
orcid.org
https://orcid.org/oauth/authorize?
client_id=0000-0002-3003-7862&
response_type=code&
scope=/activities/read-limited%20/activities/update&
redirect_uri=https://my.URL.org&
family_names=Paglione&given_names=Laura&email=l.paglione
%2B2014@orcid.org&orcid=0000-0001-6356-0580
The base URL – displays the screen
who’s asking?
what permission?
where the user goes next
Personalize the
experience
The OAuth call: part I

17. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
what the user sees
orcid.org

18. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
the OAuth calls – magic code
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 something useful to the user
• Authorize: thanks for your permission!
• Deny: are you sure you don’t want to give permission?
The magic code

19. 18 July 2016 orcid.org 19
Part 1: Collect iD

20. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
the OAuth calls – the call
orcid.org
use the code to gain access using the ORCID API
https://api.orcid.org/oauth/token
HEADER: accept:application/json
DATA:
client_id=0000-0002-3003-7862
client_secret=f6ffa224-dc28-4c51-8c9e-ae4b86f61bc3
grant_type=authorization_code
code=htA3yE
redirect_uri=https%3A%2F%2Fmy.URL.org
our API calls
always looks
like URLs
(RESTful)what format?
The magic code
confirming that you are
the right one to get this
information

21. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
the OAuth calls – the result
orcid.org
the result of the call
"access_token” : "6710dfee-6aab-445b-a266-205dd9085273",
"token_type” : "bearer",
"expires_in” : 631138518,
"scope” : "/activities/read-limited /activities/update",
"orcid” : "0000-0001-6356-0580",
"name” : "Laura Paglione”
store the access token and iD
when permission expires (in seconds)
your permission – executed contract
iD & name for the person
who gave permission
What you can do
✔ iD Collected!

22. 18 July 2016 orcid.org 22
Part 2: Display

23. You have the iD, now display it!
iDs in print
Royal Society, Biology Letters
The image cannot be displayed. Your computer may not have enough memory to open the image, or the image may have been corrupted. Restart your computer, and then open the file again. If the
red x still appears, you may have to delete the image and then insert it again.
iDs electronically
Nature, Genetics
orcid.orgPHOTO: Job Meeting
www.flickr.com/photos/jobmeeting/14375164286

24. You have the iD, now display it!
Hindawi, Geometry
orcid.org
PHOTO: Job Meeting
www.flickr.com/photos/jobmeeting/14375164286
iDs in
profiles

25. You have the iD, now display it!
ORCID iD in DOI metadata:
<person_name>
<given_name>Karl</given_name>
<surname>Ward</surname>
<ORCID authenticated=“true”>
http://orcid.org/0000-0002-4121-9960
</ORCID>
</person_name>
• iD available in search
orcid.orgPHOTO: Job Meeting
www.flickr.com/photos/jobmeeting/14375164286

26. 18 July 2016 orcid.org 26
Part 3: Connect

27. orcid.org
Get permission, use permission
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

28. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
Use permission: API-edition
orcid.org
• Read data: GET
• Add data: POST
• Update data: PUT
BASE URL: https://api.orcid.org/v2.0/0000-0000-0000-0000
HEADERS:
accept:application/json (reading) content-type:application/json (adding /updating)
Authorization: Bearer 6710dfee-6aab-445b-a266-205dd9085273
DATA (if adding or updating):
the file location=@file_location_name
Modifiers:
/works
/update
data format
Access token from before

29. Read & update through a “message”
orcid.org

30. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
Examples
orcid.org
• Add a work:
POST https://api.orcid.org/v2.0/0000-0000-0000-0000/work
• Update employment info
PUT https://api.orcid.org/v2.0/0000-0000-0000-0000/employment
• Read updated award data from another organization
GET https://api.orcid.org/v2.0/0000-0000-0000-0000/funding/19328
include:
• Access token
• Data file location & type
Unique reference
to the award

31. 18 July 2016 orcid.org 31
Part 4: Synchronizing

32. PHOTO: electronic circuit board
www.flickr.com/photos/creative_stock/5227842611
Enabling synchronization
orcid.org
ORCID API features & tips:
• Update notifications (webhooks)
• Your system registers iDs you’re watching
• ORCID notifies when changes happen
• Internal triggers
• Employment status change
• Publication acceptance
• Publication correction
• Funding award

33. 18 July 2016 orcid.org 33
Live example
Google playground
http://tinyurl.com/zrmbxqb
Scope: /orcid-works/create
Header name: accept / Header value: application/vnd.orcid+xml
Header name: Content-type / Header value: application/vnd.orcid+xml

34. Resources
PHOTO: Stairway to somewhere © Jonathan Fenton
https://flic.kr/p/7Guxgu
member resources (includes planning & communication resources)
http://members.orcid.org
API documentation
http://members.orcid.org/api
getting authenticated ORCID iDs
http://members.orcid.org/api/tutorial-retrieve-orcid-id-curl-v12-and-earlier
vendors that support ORCID iDs
http://members.orcid.org/publisher-tools
getting help at ORCID
http://orcid.org/help/contact-us
•
•
•
•
•

35. The true power of our APIs is the flexibility to use
them in ways we haven’t even dreamed of!
TODO:
One big screenshot of websites that use ORCI

36. • Find out more at http://orcid.org
• Register at http://orcid.org/register
• Twitter @ORCID_Org / @mjbuys
36orcid.org
Thank you!
Matthew Buys
Regional Director, ORCID
m.buys@orcid.org
http://orcid.org/0000-0001-7234-3684