Are you using the API to integrate ORCID functionality into your own site? This webinar will review common workflows for linking your site, and will review some of the trickier aspects of the API. (ORCID Training Presentation - Aug 30, 2012)

1. iD
ORCID Member Site
Integration: Using the API
ORCID Launch Partner Webinar
August 30, 2012
ORCID.org

2. iD
Housekeeping
• QUESTIONS? All participants are on mute
• Type question into the “question” pane, OR raise your virtual
hand to be called on.
• Will answer questions periodically, and will unmute participants
during these times.
• RECORDING: Today’s webinar will be recorded, and will be
distributed on ORCID.org.
• If you don’t want to be recorded, use the “question” pane instead
• SUPPORT: having technical challenges? GoToWebinar can help
• Global Support: http://support.citrixonline.com/webinar
• OR… Tweet @gotowebinar
ORCID.org

3. iD
ORCID Member Site
Integration: Using the API
ORCID Launch Partner Webinar
August 30, 2012
ORCID.org

4. iD
Today’s Agenda
• About the ORCID Webinar Series
• Getting to know the ORCID API
• Common ways to use the API on your site
• About this Scholar: Display to-the-minute info on your site
• Keep us up-to-date: Get and store an ID to get regular updates
• Enhance my Record: Push updates to an ORCID Record
• Additional Resources
• Next steps
ORCID.org

5. iD
The ORCID Webinar Series
• ORCID Resources (Aug 16, 2012)
Learn about the four components of the ORCID Registry: the Players,
Account & Record, Privacy and Accessing Records. Discover what will
be included in the October launch and helpful resources.
• View the recording: http://goo.gl/nLpVE
• See the slides: http://goo.gl/nuc1W
• Member Site Integration (Aug 30, 2012)
Discover some common uses of the API, and learn how to incorporate
them into your own sites and services.
• Loading Production Data (Sep 13, 2012)
The production database will soon be live and you will be able to load
live data. Learn about common challenges and how to overcome them.
• Pre-Register: http://goo.gl/CHwCw
ORCID.org

6. iD
ORCID Member Site Integration
GETTING TO KNOW THE ORCID API
ORCID.org

7. iD
Includes future functionality…
• Some functionality describe is included in the October launch,
though are not yet present on the Developer’s Sandbox
• API Scopes
On Developer’s Sandbox by late Sept 2012
see release notes: http://dev.orcid.org/release-notes#APIV1.1.0
• orcid-record (currently orcid-profile; backward compatible)
• orcid-activities (currently orcid-works; backward compatible)
• ORCID XML Message
On Developer’s Sandbox by Sept 5, 2012
see release notes: http://dev.orcid.org/release-notes#XMLV1.0.3
• Element: grants (not yet present)
• Element: patents (not yet present)
• Element: affiliations (not yet present)
ORCID.org

8. iD
ORCID Privacy
• Information in an ORCID Record has a privacy setting
Accessible by anyone
Accessible by Account Owner, Proxy(ies),Trusted Organization(s)
Accessible by Account Owner, Proxy(ies)
• “Visibility” element in the message controls the privacy
setting
Ø Also see the first in this webinar series for more info:
http://dev.orcid.org/getting-started#Aug16
ORCID.org

9. iD
The APIs
• Public API
• No token or registration needed
• Can only access data marked as public
• Can only READ
• Member API
• Registration and token needed
• Can access data marked as public or limited
• Can READ, EDIT, APPEND; For institutions/employers, it is also
possible to CREATE
• Specific permissions must be granted by the Scholar
• ORCID Profile Change Notification API (premier members only)
ORCID.org

10. iD
The Basic API Call
• The API is RESTful and URI-based, and each call has:
• Scope
• Permission level (public or limited data)
• Timeframe
• Information about the ORCID Record is passed in an ORCID
Message
• OAuth 2.0 is used to allow the record holder to grant specific
permissions to member sites
• Permissions are enforced through an OAuth Access Token
• Error messages provide feedback on failed requests
ORCID.org

11. iD
Authenticate
• To receive privileges (trusted organization), member sites do
an authentication dance
• Request access from the user (members only) è User grants
access
• Exchange user permission to get an Access Token
(using /oauth/authenticate)
• Exchange an Access Token for ORCID data using the API calls
• The Access Token
• Token Type & Access Token - used together to authorize access to
ORCID data
• Expires In – describes how long the permission is granted
• Scope – the scope of the permission
• ORCID ID – the ID of the user who has granted permission
ORCID.org

12. iD
Public API: Read / Query
• No specific permission is needed; no access token required
Name Param Request Description
Bio orcid_id orcid-bio (or Given a contributor, give me name
blank) and affiliation data.
Activities orcid_id orcid-activities Given a contributor, tell me what
research activities they have
contributed to.
Full orcid_id orcid-record Given a contributor, tell me his/her
bio and research activities
Search search [search terms] Given search criteria, give me a
ranked list of contributor and their
bios
• API URI: http://[API Host]/[Param]/[request]
• Developers Sandbox Public API Host: devsandbox.orcid.org
ORCID.org

13. iD
Public API: Query Examples
• Retrieve Bio for scholar with ORCID ID
0000-0003-2012-0010
• GET http://devsandbox.orcid.org/0000-0003-2012-0010/orcid-bio
• -OR- GET http://devsandbox.orcid.org/0000-0003-2012-0010
• Retrieve a list of Research Activities for the scholar with
ORCID ID 0000-0003-2012-0010
• GET http://devsandbox.orcid.org/0000-0003-2012-0010/orcid-
works
• Retrieve a list of IDs & bios for the contributors to the work
with DOI=“10.1038/nbt1109-984b”
• GET http://devsandbox.orcid.org/search/orcid-bio?q=digital-
object-ids:10.1038/nbt1109-984b
ORCID.org

14. iD
Member API: Read
• Member API
Activity Method Request Scope Expires In
Read Entire GET /[orcid_id]/ orcid-record/ When revoked
Record orcid-record read-limited by user
Read Bio GET /[orcid_id]/ /orcid-bio/read- When revoked
orcid-bio limited by user
Read Research GET /[orcid_id]/ /orcid-activities/ When revoked
Activities orcid-activities read-limited by user
Read Public GET /[orcid_id]/* /read-public When revoked
Info by ORCID
• Member API URI: http://[API Host]/[Request]
• Developers Sandbox Member API Host: api.devsandbox.orcid.org
• Requires Access Token: Authenticate information sent in the
HTTP header
ORCID.org

15. iD
Member API: Append
• All Members
Activity Method Request Scope Expires
In
Add a Research POST /[orcid_id]/ /orcid-activities/ 1 hour
Activity orcid-activities create
Add an External POST /[orcid_id]/ /orcid-bio/ 1 hour
Identifier orcid-bio/ external-
external- identifiers/create
identifiers
• For Institutions only
Activity Method Request Scope Expires In
Create a new POST /orcid-profile /orcid- When
ORCID Record record/create revoked by
ORCID
ORCID.org

16. iD
Member API: Update
• All Members
Activity Method Request Scope Expires
In
Update Bio PUT /[orcid_id]/ /orcid-bio/update 5 min
orcid-bio
Update Research PUT /[orcid_id]/ /orcid-activities/ 5 min
Activities orcid-activities update
• Should be used with caution
• Replaces ALL data formerly stored
• 1-hour and 5-min timeframes are also single use
ORCID.org

17. Member API: iD
Anatomy of an HTTP Header
• Command Line Request:
• curl -v -i -L -H 'Accept: application/xml' -H 'Authorization:
Bearer 1641444e-c0cb-48b1-be47-534941db139f' 'http://
api.devsandbox.orcid.org/search/orcid-bio?q=thorisson’
The API
• Resulting HTTP Header: Request
GET /search/orcid-bio?q=thorisson HTTP/1.1
User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4
OpenSSL/0.9.8r zlib/1.2.5
Made to the
Host: api.devsandbox.orcid.org Member API Host
Accept: application/xml
Authorization: Bearer 1641444e-c0cb-48b1-be47-534941db139f
Please provide the Received from the
Result in XML format Access Token
ORCID.org

18. iD
The API Message
Ø http://orcid.github.com/ORCID-Parent/schemas/orcid-message/1.0.3/
• Describe the XML message and its sections
• Biography – includes: ORCID
Record
• Lists of External Identifiers Biography
• Lists of Affiliations Activities
• Research Activities • Works
• Works • Grants
• Technologies
• Grants
• Technologies (including patents)
• Message Data Return Formats
ORCID.org

19. iD
ORCID Member Site Integration
COMMON WAYS TO USE THE API
ORCID.org

20. Using the API: iD
About this Scholar
A website displays info from the ORCID Record of scholar who has an ID
1 2 3
User is on a site Site performs a search based Site parses the
and wants more on known information. returned ORCID
info about a scholar Message & displays
public data to user
What to Query? Public API Search Display Data
http://devsandbox.orcid.org/search/
orcid-bio/?q=[search terms]
ORCID.org

21. Other Uses: iD
About this Scholar
This process can be used in several situations:
• Filling a form about the user by pulling from their ORCID Record
• Filling a form about collaborators when the researcher knows
their ORCID IDs
• Displaying “works by this scholar” by receiving a current list from
the scholar’s ORCID Record
• Use information in an ORCID Record to help identify conflict-of-
interest challenges for peer reviews
ORCID.org

22. Using the API: iD
Keep Us Up-to-date
A Scholar establishes a trust relationship while at a member site
1 2 3
? READ
READ
READ
Member site asks Scholar reviews the Member site becomes
for ongoing READ request and establishes trusted; may receive
permissions from a trust relationships record updates
Scholar
OAuth Dance OAuth/authenticate API GET read-limited
Get & store “until revoked” read- api.devsandbox.orcid.org/
limited access token [orcid_id]/orcid-record
ORCID.org

23. Other Uses: iD
Keep Us Up-to-date
This process can be used in several situations:
• Updating your records for a researcher
• Trigger an activity when certain items change for a researcher
• NOTE: Callback API can be used to automatically be notified
when things change on the scholar’s record.
ORCID.org

24. Using the API: iD
Enhance My Record
A Scholar establishes a trust relationship with member site to add to their Record
1 2 3
ADD TO READ
APPEND
READ
APPEND
? READ
Member site asks Scholar reviews the Member site becomes
for one-time request and establishes trusted; may add
APPEND trust relationships activities one time
permission
OAuth Dance OAuth authenticate API POST
Get ONE TIME access token api.devsandbox.orcid.org/
/orcid-activities/create [orcid_id]/orcid-activities
ORCID.org

25. Other Uses: iD
Enhance My Record
This process can be used in several situations:
• Encouraging a researcher to add their ORCID ID by offering to
add the manuscript to their record.
• Offer to add a list of research activities to a researcher’s record
in exchange for reviewing the data that your site has stored for
him/her.
ORCID.org

26. iD
ORCID Member Site Integration
ADDITIONAL RESOURCES
ORCID.org

27. iD
Key Resources
• Developer Technical Documentation
http://dev.orcid.org/resources
• Structure of the ORCID ID
http://dev.orcid.org/structure-orcid-identifier
• Read / Query API
http://dev.orcid.org/docs/query-api
• Update / Append API
http://dev.orcid.org/docs/deposit-update-api
• The ORCID API Message
http://orcid.github.com/ORCID-Parent/schemas/orcid-message/1.0.3/
• UML Flow Diagram
http://goo.gl/I9wIB
• Technical Support (Available after launch)
ORCID.org

28. iD
To Be Released in October
For Individuals
• Public Registry – Anyone can create an ORCID ID and search
the Registry
• ORCID Record
• Link ID to other identifier schemes, synch data
• Enhance ID with information on research activities, including
biography, works, grants and technology/products
For Member Organizations
• Updated APIs / XML
• Create IDs for employees and students (institutions only)
• Trusted relationship management to share information
ORCID.org

29. iD
Resource: News/Documentation
• Developers Portal (dev.orcid.org)
• Latest about the Launch (dev.orcid.org/launch)
• Documentation, code samples (dev.orcid.org/resources)
• Blog with the latest updates (dev.orcid.org/blog)
• Links to support (available in Oct)
ORCID.org

30. iD
Resource: Sandbox-Try the API
• Sandbox Site (devsandbox.orcid.org)
• Fully functioning API
• Tokens available at dev.orcid.org/create-client-app
• Limited web interface
• In synch with the production server and Registry
• Non-persistent. Data is refreshed periodically
ORCID.org

31. iD
Next Steps
q Get a token to use the Sandbox
(dev.orcid.org/create-client-app)
q Review documentation
(dev.orcid.org/resources)
q Signup for the next webinar
(/goo.gl/dGrRe)
• Sep 16—Loading Production Data
q Subscribe to the blog for the latest updates
(RSS: dev.orcid.org/blog/51/feed)
ORCID.org

32. iD
Laura Paglione
Technical Director
ORCID
l.paglione@orcid.org
THANK YOU!
ORCID.org