ORCID Deposit/Update API Phase 1

ORCID Deposit/Update API Phase 1

Table of Contents
ORCID Deposit/Update API Phase 1
Table of Contents
Document history
Overview
API Use Cases
User grants read access to all details
User grants read access to biographical details only
User grants read access to works only
User grants update access to biographical details only
User grants permission to add a new work
User grants update access to all works
User grants permission to add a new external identifier
User authenticates and identifies themselves
Client system creates new ORCID profile
Client system reads public data
Content Negotiation
Error responses
Top level client workflow
XML message structure
Visibility and scope attributes
Data types in XML message
Dates
Personal names
Schema Documentation
Example Results Files
References

1

Document history
Authors: Will Simpson (Semantico), Declan Newman (Semantico), Geoffrey Bilder
(ORCID)

V1: 26-OCT-2011
V2: 28-OCT-2011 Added definition of Tier 1 versus Tier 2.
Reduced time limit for time limited API calls.
Renamed 'trusted client' to 'top level client'.
Moved <contact-details> back into <orcid-bio> in associated
sample XML documents.
Added requirement for client system to ask the user to check
that work to be added is not a duplicate.
Removed <num-vols>.
V3:01-NOV-2011 Import to Google Docs, clean-up formatting, spelling.

V4:01-NOV-2011 Added link to example XML

V5:02-NOV-2011 Added new sections on error handling, and content
negotiation.

V6:09-NOV-2011 Emphasized semi-automated, researcher supervised API
calls.
Added single use access token.
Clarified meanings of scope and visibility XML attributes.
Added link to schema and documentation.

V7:12-DEC-2011 Added authenticate scope

V8:15-FEB-2012 Removed x- from mime types

V9:16-FEB -2012 Added scope for reading public data only

V10:21-AUG-2012 Updated to match schema version 1.0.3

2

Overview
The ORCID Tier 1 API will be made available to the general public, and will be used
without any authentication. This API will return only data marked as “public”, and will
not be covered by a service level agreement. The Tier 1 API is defined in another
specification document.

This document provides detailed specification of Tier 2 ORCID API calls, based on
the initial specification (Taylor & Bilder, 2011).

The ORCID Tier 2 API will be made available to third parties requiring production-
level integration of the ORCID service, and will come with defined service level
agreements. In addition to providing all the functionality available in Tier 1, it will
allow third parties to retrieve 'limited' profile data and update profile data, for those
users who have authorized them to do so.

It should be emphasized that, with the exception of batch creation of new profiles,
the API calls are designed for semi-automated, researcher supervised updates and
additions to the profile. They are not meant to support fully automated updates or N-
way synchronisation.

We believe that speed and breadth of adoption by third parties will be the ultimate
measure of success of the ORCID API. So, the key goal of this specification is to
ensure that integration with the ORCID API is as easy as possible. This will be
enabled by the following qualities.

● Easy to read and understand responses
● Consistent API message format, URL structure, and security model
● Easy to create tools for
● Use of standard data types wherever possible
The full ORCID XML schema and documentation can be found at the following URL.

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

Example ORCID files can be found at:

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

3

NEW

API Use Cases
This section specifies use cases of the API, where different levels of access are
granted by the ORCID user to third party systems. In OAuth terminology, the ORCID
user is the resource owner, and the third party system is the client system (Hammer-
Lahav, Recordon & Hardt, 2011).

In each case, the client system requests OAuth authorization for the given scope.
The client system obtains the authorization code and access token in accordance
with the OAuth2 specification.

For profiles that have been confirmed by the researcher or contributor, the client
system must request authorization for each and every update or addition to the
profile. So, ORCID will issue an access token that will be valid for a single update
only. This token will be expired immediately after the first successful PUT or POST
request.

Also, the OAuth access token will be valid only within the time frame specified
below. In other words, the access token will expire after the given time, regardless of
whether the update was made.

The client system may use the associated OAuth refresh token to get another
token. However, if an update or create scope was initially requested, this will be
downgraded to read-limited or read-only respectively.

The client system then makes the ORCID API call, passing the access token
acquired via OAuth, with the URL and HTTP method shown below.

The body of the HTTP request is used to upload new data, for API calls that are for
creating or updating ORCID data.

The result is then returned by the ORCID API, and the ORCID database is updated if
necessary.

User grants read access to all details
This call should be used when the client system wants read access to data that the
researcher or contributor has marked as accessible only by client systems that they
have specifically authorized (in other words, the data are marked as limited).

OAuth scope /orcid-profile/read-limited

OAuth time frame Until revoked by the researcher or contributor

HTTP Method GET

URL /{ORCID}/orcid-profile

Request body None

Success HTTP code 200 OK

4

Success result <orcid-message> returned, including all details even if the researcher or
contributor has marked them in ORCID as limited

User grants read access to biographical details only
This call should be used when the client system wants read access to data in <orcid-
bio> that the researcher or contributor has marked as accessible only by those
clients that they have specifically authorized (in other words, the data are marked as
limited).

OAuth scope /orcid-bio/read-limited


HTTP Method GET

URL /{ORCID}/orcid-bio

Request body None


Success result <orcid-message> returned, containing just <orcid-bio>. Includes all
details in the <orcid-bio>, even if the researcher or contributor has
marked them in ORCID as limited

User grants read access to works only
This call should be used when the client system wants read access to data in <orcid-
works> that the researcher or contributor has marked as accessible only by those
clients that they have specifically authorized (in other words, the data are marked as
limited).

OAuth scope /orcid-works/read-limited


HTTP Method GET

URL /{ORCID}/orcid-works

Request body None


Success result <orcid-message> returned, containing just <orcid-works>. Includes all
details in the <orcid-works>, even if the researcher or contributor has
marked them in ORCID as limited

User grants update access to biographical details only

5

This call should be used when the client system wants to update the researcher or
contributor's biographical details.

OAuth scope /orcid-bio/update

OAuth time frame Single update, within 5 minutes

HTTP Method PUT

URL /{ORCID}/orcid-bio

Request body <orcid-message> containing just <orcid-bio>


Success result <orcid-message> containing just <orcid-bio> returned. <orcid-bio> is
updated in database.

User grants permission to add a new work
This call is used when the client system wants to add a new work to the researcher
or contributor's list of works.

The client system should ask for confirmation from the researcher or contributor
before adding a work, to avoid adding duplicate works to the list. The confirmation
process should include showing the current list of works for the user to check
against.

So, the scope /orcid-works/create inherits /orcid-works/read-limited, so that the full
current list of works can be shown to the user.

OAuth scope /orcid-works/create

OAuth time frame Single create, within 5 minutes

HTTP Method POST


Request body <orcid-message> containing just <orcid-work>

Success HTTP code 201 Created

Success result <orcid-message> containing just <orcid-work> returned. <orcid-work> is
added to the list of works in the database.

User grants update access to all works
This call should be used when the client system wants to update the researcher or
contributor's list of works. This will allow the client system to add, remove and re-
order works.

OAuth scope /orcid-works/update

6

OAuth time frame Single update, within 5 minutes

HTTP Method PUT


Request body <orcid-message> containing just <orcid-works>


Success result <orcid-message> containing just <orcid-works> returned. All existing
works in the database are replaced by the new list of works.

User grants permission to add a new external identifier
This call should be used when the client system wants to add an external identifier to
the researcher or contributor's biographical details.

OAuth scope /orcid-bio/external-identifiers/create

OAuth time frame Single create, within 5 minutes

HTTP Method POST

URL /{ORCID}/orcid-bio/external-identifiers

Request body <orcid-message> containing just <external-identifiers>


Success result <orcid-message> containing just <external-identifiers> returned. Any
<external-identifier> in the POSTed message is added to the list of external
identifiers in the database (unless it already exists).

User authenticates and identifies themselves
This call should be used when the client system wants to use the ORCID system as
an authentication provider, but does not need privileged access T2 API data. In other
words, the client system wants the researcher or contributor to log in to the client
system using their ORCID user name and password.

The workflow is the same as for other user authorized T2 API calls, and so uses the
OAuth authorization code grant type.

The client system will be able to retrieve an access token using the authorization
code, as normal, but the access token will not allow any privileged access to the
researcher or contributor’s ORCID data.

The user’s ORCID is returned in the access token response, so the client system can
identify the user.

The client system will be responsible for logging the user out of the client system, for
example by expiring the user’s session. Logging out does not involve any interaction
with ORCID.

7

OAuth scope /authenticate

OAuth time Single authentication
frame

HTTP No API calls allowed. Client retrieves OAuth access token only.
Method

URL No API calls allowed. Client retrieves OAuth access token only.

Request body No API calls allowed. Client retrieves OAuth access token only.

Success No API calls allowed. Client retrieves OAuth access token only.
HTTP code

Success OAuth redirect back to the client system will contain the URL
result parameter ‘user_oauth_approval=true’ and the client system will be able to retrieve
an access token. The access token JSON response includes the ORCID of the user.

Client system creates new ORCID profile
This call should be used when the client system wants to create a new profile on
behalf of a researcher or contributor. The client system may be doing this as part of
creating a large batch of new profiles.

This call is different to API calls mentioned above, because it does not require
authorization from a researcher or contributor (the person in question has not yet
registered in the system). Instead, the authorization is pre-arranged with ORCID
(Hammer-Lahav, 2011, section 4.4). The permission will be added to the client
system's profile by an ORCID administrator. The workflow is described in more detail
in the section below called ‘Top level client workflow’.

OAuth scope /orcid-profile/create

OAuth time frame Until revoked by ORCID administrator

HTTP Method POST

URL /orcid-profile

Request body <orcid-message> containing just <orcid-profile> without ORCID identifier


Success result <orcid-message> containing just <orcid-profile> with a new ORCID
identifier. The new profile is created in the database, and is flagged as not
confirmed by the researcher or contributor.

The /orcid-profile/create scope will also give the client system permission to update
profiles that it created but have not yet been confirmed, without requiring user
authorization. Once the profile has been confirmed, the client system must request
authorization from the user for each and every update or addition.

Client system reads public data

8

This scope should be used when the client system wants only to read public data
from the T2 API. In other words, the client wants to use the T2 API as if it is the
public T1 API. The client may want to do this to take advantage of a service level
agreement they have for the T2 API.

So, this scope does not require authorization from a researcher or contributor. The
client will use the OAuth2 client credentials grant type to obtain the token.

OAuth scope /read-public

OAuth time frame Until revoked by ORCID administrator

HTTP Method GET

URL {ORCID}/*

Request body None


Success result <orcid-message> containing only public data relevant to the specified URL

9

Content Negotiation
The URL in REST API calls determines which subset of data is returned. In other
words, there is a different URL for biographical details, list of works, and full profile.

However, the URL does not specify the format used to represent the data. This is
determined using Internet media types in the Accept header in the HTTP request.

The following representations will be supported in Phase 1.

Internet media type Description

application/orcid+xml XML conforming to orcid-message.xsd

application/orcid+json JavaScript Object Notation equivalent of the XML

text/html Redirects to the ORCID web user interface to display the result

For ease of integration, the standard XML and JSON types can be used in place of
the above.

application/xml
application/json

The response data for these will be the same as the equivalent orcid mime type. The
only difference in the response will be the Content-Type header, which will exactly
match the content type that was requested.

Future versions of the ORCID API may support additional formats, for example
application/rdf+xml.

10

Error responses
If an error occurs that means that the request cannot be fulfilled, then the ORCID API
will respond using standard HTTP error codes.

In addition, the response body will contain a descriptive error message. This will be
in the format that was requested. In other words, if the original call requested XML,
then the error message will be in XML. However, if the original call requested JSON,
then the error message will be in JSON.

Here is an example in XML format.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<orcid-message xmlns="http://www.orcid.org/ns/orcid">

<error-desc>Cannot find details for 4444-4444-4444-</error-desc>

</orcid-message>

The most important error conditions are as follows.

HTTP error code error-desc

401 Unauthorized You are not authorised to access this resource

404 Not Found Cannot find details for {ORCID}

11

Top level client workflow
Certain top level clients will be able to bulk create new ORCID profiles. A
permissions based workflow needs to be put in place to allow them the necessary
access.

This is sometimes known as the trusted client workflow in OAuth, and uses
the 'client_credentials' grant type. The OAuth specification for this workflow can be
found at: http://tools.ietf.org/html/draft-ietf-oauth-v2-22#section-4.4

The steps to grant an institution's application permissions to access the ORCID API
will be the following:

1. An institution registers an application in the ORCID web application.
2. The “client id”, “client secret” and “access token” are created and displayed.
At this point, the access token will allow the client system to access the Tier 2 API
with read-only access.

When the client application requests access to a researcher or contributor's limited
data, or wants to update their data, the application will still need to use the access
token generated when the user has approved access, as per the usual 'authorization
code' OAuth workflow.

However, if that client application needs to bulk create new ORCID profiles on behalf
or their researchers, then they will contact the ORCID support team and request the
additional permission to do so. If, and when, this is granted, the client application
administrator will need to log into the ORCID user interface and generate a new
access token. Alternatively, the client application will be able to generate a new
access token with scope “create” via the existing “/oauth/token” end-point.

The temptation to require an access token for all tier 1 and 2 API calls is quite
compelling, but after some deliberation, we came to the conclusion that this would
not conducive of one of our most important design goals, which is to make both tiers
as friendly as possible.

12

XML message structure
The structure of ORCID API response reflects the use cases, and the security
model. In others words, a request for authorization to read or update a set of fields
corresponds to a single XML element in the response.

The XML elements that correspond to OAuth scopes are 'first class citizens' in the
ORCID XML.

XML element Description Notes
<orcid> The Open Immutable
Researcher &
Contributor Identifier
<orcid-history> The history of the This is maintained internally by ORCID
record within ORCID so would never be updated directly by
external client systems. It is a basic log
of when the profile was created, etc.
<orcid-bio> The biographical The researcher or contributor can grant
details of the update access to the whole of their
researcher or biographical details.
contributor
<contact-details> The contact details The researcher or contributor
of the researcher or should have the option to make their
contributor biographical details available to the
public API, without exposing their
personal contact details.
<external-identifiers> Identifiers from We should allow for the possibility of
systems other than cross-posting of identifiers from other
ORCID systems. In this case the researcher or
contributor would only want to allow an
external identifier to be added, without
exposing access to any other data.
<orcid-works> The works by the The researcher or contributor can
researcher or choose to grant access for adding a
contributor new work – this is analogous to posting
the new work to their Twitter time-line.
Also, the researcher or contributor can
grant the client system full control over
their entire list of works.

The above structure is shown in orcid-profile-message.xml, orcid-bio-message.xml,
and orcid-works-message.xml.

13

Visibility and scope attributes
Each of the first class citizens in the ORCID XML can have a scope attribute. The
scope attribute indicates the permissions the client system currently has on that
element. The possible values of the scope attribute correspond to the OAuth scopes
defined above.

● read-limited
● update
● create
For example, when a client system has been granted authorization to update the
biographic details, then API responses will contain the following.
<orcid-bio scope="update">
….
</orcid-bio>

The client system should also respect the visibility that the researcher or contributor
has assigned to each section of data. So, there will also be a visibility attribute. This
attribute can have the following values.

● private
● limited
(The value 'private' will only be used in internal messages between the ORCID web
interface and ORCID administrative utilities or systems. The ORCID web application
will have super privileges on all data, so will be able to see private data.)

The data are public if the visibility attribute is absent.

So, when the client system has been granted authorization to update the biographic
details, but the researcher or contributor has also marked the biography as limited,
then API responses will contain the following.
<orcid-bio scope="update" visbility=”limited”>
….
</orcid-bio>
If the client system does not have sufficient scope to see the data, then the element
will be absent from the response. The element will also be absent if there is not yet
any data populated for the user. So, it will not be possible to see how much additional
detail is potentially available about a specific individual, without having the necessary
permissions.

Schema Documentation
The full ORCID XML schema and documentation can be found at the following URL.

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

14

Example Results Files
Example ORCID files can be found at:

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

15

References
1. Michael Taylor, Geoffrey Bilder. (2011, October 18). ORCID Phase 1
Query API: https://docs.google.com/document/d/1hEHwKEpQ3wH-
qmgmQAgdxdcEIG1jmv6e2-FgdEfW89I/edit
2. E. Hammer-Lahav, Ed. (Yahoo!), D. Recordon (Facebook), D. Hardt
(Microsoft). (2011, September 22). The OAuth 2.0 Authorization Protocol .
Retrieved 25 October, 2011 from the Internet Engineering Task Force (IETF)
website: http://tools.ietf.org/html/draft-ietf-oauth-v2-22.

16

ORCID Deposit/Update API Phase 1

Recommended

Recommended

More Related Content

More from ORCID, Inc

More from ORCID, Inc (20)

ORCID Deposit/Update API Phase 1