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)


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) | ORCID API in action Singapore Management University 6 April 2016
  2. 2. 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
  3. 3. 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. 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. 5 Sector contributions PHOTO: Stairway to somewhere © Jonathan Fenton tps:// 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 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
  7. 7. Custom integrations Via the ORCID APIs • Fine-tuned control and permissions • Customized buttons, user flows, & user feedback Current integration list: PHOTO: Stairway to somewhere © Jonathan Fenton
  8. 8. 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 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 PHOTO: Stairway to somewhere © Jonathan Fenton
  10. 10. Elements 12 April 2016 10 • Researchers follow a link to connect their records • Elements reads the ORCID record and updates the Elements publication list
  11. 11. Pure 12 April 2016 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
  12. 12. Converis 12 April 2016 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
  13. 13. DSpace 12 April 2016 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
  14. 14. 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. 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: of-the-app-economy.html What is an API? PHOTO: 3/2 nuts © M.G. Kafkas
  16. 16. 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
  17. 17. 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 Explaining scopes / permissions 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
  20. 20. 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 OAuth in three easy steps OAuth is a standard protocol used to obtain user permission to interact with their ORCID record
  22. 22. PHOTO: electronic circuit board Step 1: Initiate the process Initiate the process: Send the user to a “fancy” URL client_id=APP-XT8FBKJRO3MR8WDR& response_type=code& scope=/orcid-profile/read-limited%20/activities/update& redirect_uri= family_names=Researcher&given_names=Bob&email=bobresearcher@mail base URL – displays the screen who’s asking? what permissions? where the user goes next personalize the experience
  23. 23. PHOTO: electronic circuit board What the user sees link from your website custom email to researchers
  24. 24. PHOTO: electronic circuit board What the user sees sign-in form registration form already signed in
  25. 25. PHOTO: electronic circuit board Step 2: Magic code & user feedback ORCID sends the user to your redirect, with a code 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 Feedback Examples from Crossref: Authorized Denied
  27. 27. Step 3a: Transform the code into a token Use the code to gain access using the ORCID API HEADER: accept:application/json DATA: client_id=APP-XT8FBKJRO3MR8WDR client_secret=e285575c-4794-464b-a807-6f1c06b63 grant_type=authorization_code code=htA3yE PHOTO: Job Meeting 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 Step 3b: Store the result 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 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 An example: get data from the record HTTP Method: GET URL: HEADERS: accept:application/json Authorization: Bearer 6710dfee-6aab-445b-a266-205dd9085273 iD and access token from OAuth calls
  31. 31. PHOTO: electronic circuit board An example: add data to the record HTTP Method: PUT URL: 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 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 API documentation List of supported vendor systems (includes details on how to connect) List of current integrations Tutorial: ORCID API (Searches, OAuth, Create on Demand) ORCID API User Listserv ORCID API Source (Github) model/src/main/resources/ • • • • • •