iD

ORCID.org

ORCID Member Site Integration: Using the API ORCID Launch Partner Webinar August 30, 2012

iD

ORCID.org

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

iD

ORCID.org

ORCID Member Site Integration: Using the API ORCID Launch Partner Webinar August 30, 2012

iD

ORCID.org

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

iD

ORCID.org

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

iD

ORCID.org

GETTING TO KNOW THE ORCID API ORCID Member Site Integration

iD

ORCID.org

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)

iD

ORCID.org

ORCID Privacy •  Information in an ORCID Record has a privacy setting

•  “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

Accessible by anyone

Accessible by Account Owner, Proxy(ies), Trusted Organization(s)

Accessible by Account Owner, Proxy(ies)

iD

ORCID.org

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)

iD

ORCID.org

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

iD

ORCID.org

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

iD

ORCID.org

Public API: Read / Query •  No specific permission is needed; no access token required

•  API URI: http://[API Host]/[Param]/[request] •  Developers Sandbox Public API Host: devsandbox.orcid.org

Name Param Request Description

Bio orcid_id orcid-bio (or blank)

Given a contributor, give me name 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

iD

ORCID.org

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

iD

ORCID.org

Member API: Read •  Member API

•  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

Activity Method Request Scope Expires In

Read Entire Record

GET /[orcid_id]/orcid-record

orcid-record/read-limited

When revoked by user

Read Bio GET /[orcid_id]/orcid-bio

/orcid-bio/read-limited

When revoked by user

Read Research Activities

GET /[orcid_id]/orcid-activities

/orcid-activities/read-limited

When revoked by user

Read Public Info

GET /[orcid_id]/* /read-public When revoked by ORCID

iD

ORCID.org

Member API: Append •  All Members

•  For Institutions only

Activity Method Request Scope Expires In

Add a Research Activity

POST /[orcid_id]/orcid-activities

/orcid-activities/create

1 hour

Add an External Identifier

POST /[orcid_id]/orcid-bio/external-identifiers

/orcid-bio/external-identifiers/create

1 hour

Activity Method Request Scope Expires In

Create a new ORCID Record

POST /orcid-profile /orcid-record/create

When revoked by ORCID

iD

ORCID.org

Member API: Update •  All Members

•  Should be used with caution •  Replaces ALL data formerly stored

•  1-hour and 5-min timeframes are also single use

Activity Method Request Scope Expires In

Update Bio PUT /[orcid_id]/orcid-bio

/orcid-bio/update 5 min

Update Research Activities

PUT /[orcid_id]/orcid-activities

/orcid-activities/update

5 min

iD

ORCID.org

Member API: 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’

•  Resulting HTTP Header: 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 Host: api.devsandbox.orcid.org Accept: application/xml Authorization: Bearer 1641444e-c0cb-48b1-be47-534941db139f

The API Request

Made to the Member API Host

Received from the Access Token

Please provide the Result in XML format

iD

ORCID.org

The API Message •  Describe the XML message and its sections •  Biography – includes:

•  Lists of External Identifiers •  Lists of Affiliations

•  Research Activities •  Works •  Grants •  Technologies (including patents)

•  Message Data Return Formats

Biography Activities •  Works •  Grants •  Technologies

ORCID Record

Ø  http://orcid.github.com/ORCID-Parent/schemas/orcid-message/1.0.3/

iD

ORCID.org

COMMON WAYS TO USE THE API ORCID Member Site Integration

iD

ORCID.org

Using the API:

About this Scholar

User is on a site and wants more info about a scholar

Site performs a search based on known information.

Site parses the returned ORCID Message & displays public data to user

1 2 3

A website displays info from the ORCID Record of scholar who has an ID

What to Query? Public API Search Display Data

http://devsandbox.orcid.org/search/orcid-bio/?q=[search terms]

iD

ORCID.org

Other Uses:

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

iD

ORCID.org

Using the API:

Keep Us Up-to-date

Member site asks for ongoing READ permissions from a Scholar

Scholar reviews the request and establishes trust relationships

READ READ

Member site becomes trusted; may receive record updates

1 2 3

A Scholar establishes a trust relationship while at a member site

OAuth Dance OAuth/authenticate

READ

?

API GET read-limited api.devsandbox.orcid.org/[orcid_id]/orcid-record

Get & store “until revoked” read-limited access token

iD

ORCID.org

Other Uses:

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.

iD

ORCID.org

Using the API:

Enhance My Record

Member site asks for one-time APPEND permission

Scholar reviews the request and establishes trust relationships

APPEND READ

READ ADD TO

Member site becomes trusted; may add activities one time

1 2 3

A Scholar establishes a trust relationship with member site to add to their Record

OAuth Dance OAuth authenticate

APPEND READ ?

API POST

api.devsandbox.orcid.org/[orcid_id]/orcid-activities

Get ONE TIME access token /orcid-activities/create

iD

ORCID.org

Other Uses:

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.

iD

ORCID.org

ADDITIONAL RESOURCES ORCID Member Site Integration

iD

ORCID.org

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)

iD

ORCID.org

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

iD

ORCID.org

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)

iD

ORCID.org

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

iD

ORCID.org

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)

iD

ORCID.org

THANK YOU!

Laura Paglione Technical Director ORCID l.paglione@orcid.org