ORCID Deposit/Update API Phase 1

ORCID Deposit/Update API Phase 1Table 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 historyAuthors: Will Simpson (Semantico), Declan Newman (Semantico), Geoffrey Bilder(ORCID)V1: 26-OCT-2011V2: 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

OverviewThe ORCID Tier 1 API will be made available to the general public, and will be usedwithout any authentication. This API will return only data marked as “public”, and willnot be covered by a service level agreement. The Tier 1 API is defined in anotherspecification document.This document provides detailed specification of Tier 2 ORCID API calls, based onthe 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 levelagreements. In addition to providing all the functionality available in Tier 1, it willallow third parties to retrieve limited profile data and update profile data, for thoseusers 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 andadditions 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 ultimatemeasure of success of the ORCID API. So, the key goal of this specification is toensure that integration with the ORCID API is as easy as possible. This will beenabled 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 possibleThe 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 limitedUser 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 OAuth time frame Until revoked by the researcher or contributor HTTP Method GET URL /{ORCID}/orcid-bio Request body None Success HTTP code 200 OK 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 limitedUser 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 OAuth time frame Until revoked by the researcher or contributor HTTP Method GET URL /{ORCID}/orcid-works Request body None Success HTTP code 200 OK 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 limitedUser grants update access to biographical details only 5

This call should be used when the client system wants to update the researcher or contributors 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 HTTP code 200 OK 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 contributors 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 URL /{ORCID}/orcid-works 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 contributors 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 URL /{ORCID}/orcid-works Request body <orcid-message> containing just <orcid-works> Success HTTP code 200 OK 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 contributors 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 HTTP code 201 Created 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 systems 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 HTTP code 201 Created 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 datafrom the T2 API. In other words, the client wants to use the T2 API as if it is thepublic T1 API. The client may want to do this to take advantage of a service levelagreement they have for the T2 API.So, this scope does not require authorization from a researcher or contributor. Theclient 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 HTTP code 200 OK 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 institutions 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 contributors 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 FilesExample 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

http://support.orcid.org	460
http://orcid.uservoice.com	14

ORCID Deposit/Update API Phase 1

by ORCID on Sep 28, 2012

Zugänglichkeit

Details hochladen

Benutzerrechte

2 Einbettungen 474

Statistiken

ORCID Deposit/Update API Phase 1 Document Transcript