An API tutorial

1. i
The Jisc UK ORCID Use cases and API
workshop: API tutorial
30th September
2o16

2. Jisc UK ORCID Consortium
»Monica Duke – main presenter
»Helpers
›Alan Stiles (The Open University)
›PeterWest (Digital Repository
Services Ltd)
13/10/2016 Jisc - UKORCID support workshop 2

3. ORCID tutorial atVALA2016
We will be following a tutorial provided by ORCID
https://github.com/alainna/VALA2016
Source:
– http://www.vala.org.au/vala2016-conference-program/boot-
camp-2016/1064-vala2016-boot-camp-session-1
– http://www.vala.org.au/direct-download/vala2016-
proceedings/vala2016-slides/832-vala2016-bootcamp-session-
1-paglione-slides/file
13/10/2016 Jisc - UKORCID support workshop 3

4. The ORCID APIs
» The Sandbox is not connected to the production ORCID
registry and no information is shared between the two
systems, however, the Sandbox has identical functionality,
with the some exceptions (next slide)
» The Public API allows organizations that are not ORCID
members to access a limit set of API features, including
authenticating users' ORCID iDs and retrieving publicly-
visible information from the ORCID registry.
» Access to any of the ORCID APIs requires a set of credentials
consisting of a Client ID and a Client Secret (see slide 6 for
how to register to use each of theAPIs)
13/10/2016 Jisc - UKORCID support workshop 4

5. API comparison
13/10/2016 Jisc - UKORCID support workshop 5
Public Member
Production Available to anyone
Can be used to authenticate
researchers as well as search for
and retrieve public data from
researchers' ORCID records.
https://pub.orcid.org/v1.2/
Only available to organizations that have
become ORCID members
Allows members to authenticate researchers,
access read-limited information, edit, and
update ORCID records
(provided that they have first obtained the
researcher's permission)
https://api.orcid.org/v1.2/
Sandbox Resemble the production Registry as closely as possible
ImportWorks tools do not work; Not indexed by search engines
Only sends email messages to @mailinator.com email addresses.
Disclaimers: No Service-Level Agreement on the Sandbox; No guarantees about
uptime/availability, processing speed, or data availability; No data backup in the
Sandbox, and right is reserved to remove data at any time
http://pub.sandbox.orcid.org/v1.2/ http://api.sandbox.orcid.org/v1.2/

6. API comparison
13/10/2016 Jisc - UKORCID support workshop 6
Production Sandbox
Credentials are requested for the specific API
Public Request individual developer tools after signing in to your record
https://members.orcid.org/api/accessing-public-api
http://orcid.org/signin http://sandbox.orcid.org/signin
Member Need to be a member organisation
https://orcid.org/content/register-client-
application-production-trusted-party
Requires demo against Sandbox or
vendor approved system
Credentials also give access to public API
Membership is not required in order to
access the Sandbox Member API.
Register a client application
https://orcid.org/content/register-client-
application-sandbox
http://support.orcid.org/knowledgebase/articles/895965-what-s-the-difference-between-the-public-and-membe
http://orcid.org/about/membership/comparison
https://members.orcid.org/api
http://support.orcid.org/knowledgebase/articles/166623-is-the-sandbox-different-from-the-production-regis
http://orcid.org/organizations/integrators/API

7. Member API credentials application
» Form:
› https://orcid.org/content/register-client-application-
production-trusted-party
»Help to fill in the form:
› http://support.orcid.org/knowledgebase/articles/116739
-register-a-client-application
»Checking your demo application:
› https://members.orcid.org/api/member-credential-
check-list
13/10/2016 Jisc - UKORCID support workshop 7

8. API release versions
» We have used version 1.2 (most stable, unchanging)
» Newer versions: Less tested than stable release
» candidates may contain bugs
» summary of changes from rc1 to rc2
» Announced on the API list
» Suitable for those that can keep up with rapid development
cycles (weeks)
» https://members.orcid.org/api/news/api-version-20rc2-
released
13/10/2016 Jisc - UKORCID support workshop 8

9. Introduction to scopes
https://members.orcid.org/api/orcid-scopes
»The scope is the permission requested.
»Each access token has a particular scope (set of
permissions) associated with it.
»The user grants the permission for that scope
»Token is valid for that scope(s)
»Multiple scopes can be requested
13/10/2016 Jisc - UKORCID support workshop 9

10. Scope types
13/10/2016 Jisc - UKORCID support workshop 10
Scope
/authenticate Both member and public API
to collect ORCID only
included in other scopes (can be omitted)
MEMBER ONLY API
/read-limited get access to public and limited visibility items
/activities/update to write, update and delete items in the education,
employment, funding, works and peer-review sections
/orcid-bio/update to write, update and delete items in the other-names,
keywords, countries, researcher-urls, websites, and
personal external identifiers sections of the record
Complete access: /read-limited /activities/update and /orcid-bio/update

11. Scope types
13/10/2016 Jisc - UKORCID support workshop 11
Scope
2 legged oauth Requested directly from the ORCID API
Do not require the researcher to grant permission
Long-lived
/read-public This scope is used to read public information on a single
ORCID iD or search forORCID records.
/webhook This scope allows a client application to register a webhook
on an ORCID record, in order to receive notifications when a
record is updated.
Premium only

12. Scopes errors
401.Invalid access token
Ensure that the access token used for the call is complete, matched
to the ORCID iD and scope of the call, and is not expired
403.Security problem : Insufficient or wrong scope
Check that the access token has permission for the action you are
taking and that you are using the correct end-point and method.
405.Method Not Allowed
Ensure that the scope of your authorization token matches the call
you are making, and that you are posting to the MemberAPI base
URL (i.e., api.sandbox.orcid.org)
13/10/2016 Jisc - UKORCID support workshop 12

13. Resources and help
» UK helpdesk: ukorcidsupport@jisc.ac.uk
» About the API https://members.orcid.org/api
› Https://members.orcid.org/api/api-calls
» Error codes https://members.orcid.org/api/api-error-codes
» Tutorials: https://members.orcid.org/api/tutorial-retrieve-
orcid-id
» FAQ/knowledgebase:
http://support.orcid.org/knowledgebase
» http://support.orcid.org/knowledgebase/topics/124401-
frequently-asked-questions-about-the-orcid-api
13/10/2016 Jisc - UKORCID support workshop 13

14. Jisc UK ORCID Consortium
»Questions?
13/10/2016 Jisc - UKORCID support workshop 14

15. jisc.ac.uk
Contact: Monica Duke
JISC UK ORCID technical and
community support co-ordinator
monica.duke@jisc.ac.uk
13/10/2016 Jisc - UKORCID support workshop 15