Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

ORCID API in Action (A. Wrigley)

496 views

Published on

Presentation at the 2016 ORCID Singapore Workshop (6 April 2016)

Published in: Education
  • Be the first to comment

  • Be the first to like this

ORCID API in Action (A. Wrigley)

  1. 1. 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) support@orcid.org | orcid.org/0000-0002-6036-0903 ORCID API in action Singapore Management University 6 April 2016
  2. 2. 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. Kafkas https://flic.kr/p/4XytpS
  3. 3. orcid.org 3 • PLAN Plan how the integration will work • BUILD Build and test your integration • COMMUNICATE Design & build connection points Integrating in 3 steps
  4. 4. orcid.org 4 • PLAN: Plan how the integration will work Use 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
  5. 5. 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
  6. 6. 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
  7. 7. 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
  8. 8. 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 support Member 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
  9. 9. 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
  10. 10. Elements 12 April 2016 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/
  11. 11. Pure 12 April 2016 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
  12. 12. Converis 12 April 2016 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
  13. 13. DSpace 12 April 2016 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
  14. 14. 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
  15. 15. 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. Kafkas https://flic.kr/p/4XytpS
  16. 16. 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. Kafkas https://flic.kr/p/4XytpS
  17. 17. 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
  18. 18. PHOTO: electronic circuit board www.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)
  19. 19. What a message looks like orcid.org
  20. 20. 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
  21. 21. PHOTO: electronic circuit board www.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
  22. 22. PHOTO: electronic circuit board www.flickr.com/photos/creative_stock/5227842611 Step 1: Initiate the process orcid.org Initiate the process: Send the user to a “fancy” URL https://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=bobresearcher@mail inator.com base URL – displays the screen who’s asking? what permissions? where the user goes next personalize the experience
  23. 23. PHOTO: electronic circuit board www.flickr.com/photos/creative_stock/5227842611 What the user sees orcid.org link from your website custom email to researchers
  24. 24. PHOTO: electronic circuit board www.flickr.com/photos/creative_stock/5227842611 What the user sees orcid.org sign-in form registration form already signed in
  25. 25. PHOTO: electronic circuit board www.flickr.com/photos/creative_stock/5227842611 Step 2: Magic code & user feedback 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 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!
  26. 26. PHOTO: electronic circuit board www.flickr.com/photos/creative_stock/5227842611 Feedback orcid.org Examples from Crossref: Authorized Denied
  27. 27. Step 3a: Transform the code into a token orcid.org Use the code to gain access using the ORCID API https://api.sandbox.orcid.org/oauth/token HEADER: accept:application/json DATA: client_id=APP-XT8FBKJRO3MR8WDR client_secret=e285575c-4794-464b-a807-6f1c06b63 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
  28. 28. PHOTO: electronic circuit board www.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
  29. 29. 12 April 2016 orcid.org 29 Action Permission required Call Read 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?
  30. 30. PHOTO: electronic circuit board www.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 token from OAuth calls
  31. 31. PHOTO: electronic circuit board www.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+xml Authorization: Bearer 6710dfee-6aab-445b-a266-205dd9085273 DATA: the file location=@file_location_name iD and access token from OAuth calls
  32. 32. PHOTO: London, England https://flic.kr/p/qhALa3 orcid.org 32 1. Show us how the integration works 2. Request production API credentials from ORCID 3. Take the application live 4. Let everyone know! Once it’s ready, take it live
  33. 33. Resources PHOTO: Stairway to somewhere © Jonathan Fenton https://flic.kr/p/7Guxgu API documentation http://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 integrations http://members.orcid.org/current-integrations Tutorial: ORCID API (Searches, OAuth, Create on Demand) http://is.gd/VALA2016ORCID ORCID API User Listserv http://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 • • • • • •

×