Guidance on moving to ORCID 2.0 API
ORCID announced the release of version 2.0 of the ORCID API in early 2017, and expected version 1.2 of the API to be retired by the end of 2017. All consortium members have been encouraged to update system(s) before the end of 2017. A letter was sent out on 16th August to all members who have registered an integration with ORCID (i.e. have requested credentials) to ask about upgrade plans and offer support, with follow up continuing into 2018. All ORCID API users who have not done so yet should be urgently upgrading to 2.0 API and planning their migration. This page will be updated with further information as it becomes available from ORCID.
In response to the question:
Will ORCID versions pre v2.0 continue to function once support ends?
ORCID replied We are planning to sunset (switch off) the API v1.2 and all v2 release candidates by the end of the year. We will of course make sure every member has upgraded to v2.0 before we proceed to the switch-off. Should any member foresee issues meeting this deadline, we would like to be informed as soon as possible.
From ORCID’s February 2018 newsletter:
“We will be discontinuing support for our 1.2 API on August 1, 2018. All members currently on member API versions 1.1, 1.2, or 2.0 release candidates should be actively upgrading to API 2.0 or 2.1. We’ve already spoken with many of you, and, if you haven’t already done so, please contact us urgently with your timeframe for completing your 2.0 upgrade so we can plan the sunset of older API versions later this year with as little inconvenience to you and your users as possible. Please also note that older versions of the public API are scheduled to be discontinued March 1.”
What do you need to do?
If you have a vendor system, e.g. a CRIS (PURE, Symplectic, Worktribe, Converis):
The following vendor systems all have a version that supports 2.0:
- PURE version 5.9 (June 2017)
- Symplectic version 5.6 (June 2017)
- Converis version 5.10.5 (July 2017)
If you have not already upgraded to one of these versions, please plan an upgrade asap and get in touch to let us know. Most of the institutions in the UK consortium, using a vendor system, as of March 2018, have upgraded, with a small number that have agreed an extension while a planned upgrade takes place.
If you have a custom integration:
If you are not already using 2.0, you will need to urgently upgrade your systems to use version 2.0 If you’re presently developing an integration, you should develop to 2.0 which is available on the sandbox and production registries.
There are some significant changes to keep in mind:
- All redirects must be updated to HTTPS — HTTP redirect URIs no longer supported
- New scopes (Your old access tokens will still work)
- Add/edit items to record on an individual basis using put codes
- New endpoints
Using the Sandbox
For anyone testing with the release of 2.0 on Sandbox, please don’t hesitate to use the ORCID API discussion list with any questions or concerns or contact the support desk for the UK ORCID Jisc consortium if you are a member of the consortium mailto:email@example.com.
What are the improvements to the API as a result of the upgrade?
- Summary views, making large records more efficient to handle
- Support for ORCID’s peer review functionality
- Support for grouped works within the ORCID message schema, reflecting the functionality in the user interface
- Better support for the biographical information associated with the ORCID record
- Faster API calls for the most common summary information for an ORCID record
- Streamlined permission scopes
- Updated error codes and messaging
The blog post by Rob Peters, technology director at ORCID provides a good overview of changes and the reasoning behind them. ORCID’s Alainna Wrigley has also described Have you upgraded to API v2.0? Read why you should in a blog post. ORCID’s documentation is listed in detail below and an overview on moving to 2.0 is a good starting point.
What help is available?
The 2.0 API was launched on February 14th 2017. ORCID have provided a number of documents to help with this transition including:
- A list of changes from 1.2 to 2.0 (or from release candidate 2.0_rc3 to 2.0)
- Technical documentation for the 2.0 API
- The full 2.0 XSD
- Sample xml files in the v2.0 schema
- Basic API tutorials using 2.0
- Updated workflow guides
- Webinars about the update
- A detailed guide to the changes and what is required to update
ORCID will be continuing to share information about 2.0 upgrade webinars in the monthly newsletters. The next of the monthly webinars listed on the ORCID events page dedicated to the move from 1.2 to 2.0 will be held Tue, Mar 13, 2018 7:00 AM – 8:00 AM GMT. Register here. For those who cannot attend, there is a recorded webinar for service providers or a recording of Changes in 2.0.
If you have any questions or concerns, please contact the UK Consortium helpdesk in the first instance: firstname.lastname@example.org