ORCID Member Site Integration: Using the API
3 likes2,724 views
The ORCID webinar on August 30, 2012, discussed the integration of the ORCID API for member sites and highlighted common use cases for displaying scholar information. It covered functionalities of the API, privacy settings, and provided resources for further learning. Participants were encouraged to utilize the API for real-time information updates and interaction with scholar records.
![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](https://image.slidesharecdn.com/lpp-orcidapi-120925170229-phpapp01/85/ORCID-Member-Site-Integration-Using-the-API-12-320.jpg)
![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](https://image.slidesharecdn.com/lpp-orcidapi-120925170229-phpapp01/85/ORCID-Member-Site-Integration-Using-the-API-14-320.jpg)
![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](https://image.slidesharecdn.com/lpp-orcidapi-120925170229-phpapp01/85/ORCID-Member-Site-Integration-Using-the-API-15-320.jpg)
![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](https://image.slidesharecdn.com/lpp-orcidapi-120925170229-phpapp01/85/ORCID-Member-Site-Integration-Using-the-API-16-320.jpg)
![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](https://image.slidesharecdn.com/lpp-orcidapi-120925170229-phpapp01/85/ORCID-Member-Site-Integration-Using-the-API-20-320.jpg)
![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](https://image.slidesharecdn.com/lpp-orcidapi-120925170229-phpapp01/85/ORCID-Member-Site-Integration-Using-the-API-22-320.jpg)
![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](https://image.slidesharecdn.com/lpp-orcidapi-120925170229-phpapp01/85/ORCID-Member-Site-Integration-Using-the-API-24-320.jpg)
ORCID Member Site Integration: Using the API
- 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