Presentation at the 2015 November ORCID Outreach Meeting in San Francisco (3-4 November 2015)

1. orcid.org
beyond what is ORCID...
...using the API
2015 november 3
laura paglione
technical director, ORCID
L.Paglione@ORCID.org
http://orcid.org/0000-0003-3188-6273
Contact Info: p. +1-301-500-2139 a. 10411 Motor City Drive, Suite 750, Bethesda, MD 20817 USA

2. orcid.org 2
the other stuff that has to happen
• communications
• rollout timing
• evangelism – 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

3. 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

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

5. orcid.org 5
• 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

6. explaining scopes / permissions
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)
PHOTO: Job Meeting
www.flickr.com/photos/jobmeeting/14375164286

7. what a message looks like
orcid.org

8. the OAuth calls – part 1
orcid.org
Initiate the process – Send the user to a “fancy” URL
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=Paglionegiven_names=Lauraemail=l.paglione
%2B2014@orcid.orgorcid=0000-0001-6356-0580
PHOTO: Job Meeting
www.flickr.com/photos/jobmeeting/14375164286
The base URL – displays the screen
who’s asking?
what permission?
where the user goes next
Personalize the
experience

9. what the user sees
orcid.orgPHOTO: Job Meeting
www.flickr.com/photos/jobmeeting/14375164286

10. the OAuth calls – part 2
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
• thanks for your permission!
• are you sure you don’t want to give permission?
PHOTO: Job Meeting
www.flickr.com/photos/jobmeeting/14375164286
The magic code

11. the OAuth calls – part 3a: 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
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

12. the OAuth calls – part 3b: 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
PHOTO: Job Meeting
www.flickr.com/photos/jobmeeting/14375164286
when permission expires (in seconds)
your permission – executed contract
iD name for the person
who gave permission
What you can do

13. ORCID-specific calls
orcid.org
• Read data: GET
• Add data: POST
• Update data: PUT
BASE URL: https://api.orcid.org/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
PHOTO: Job Meeting
www.flickr.com/photos/jobmeeting/14375164286
Modifiers:
/works
/update
data format
Access token from before

14. but wait... there’s more
orcid.org
what is an ORCID iD, and why provide it?
• Error handling
• API updates
• about 1x/year
• supported versions
• release candidates
• deprecated versions
PHOTO: Job Meeting
www.flickr.com/photos/jobmeeting/14375164286

15. 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
•
•
•
•
•

16. thank you
● http://orcid.org
● BLOG: http://orcid.org/about/news
● TWITTER: @ORCID_Org
orcid.org