ORCID aims to support 2 major API versions at a time. When a new major API version is released, ORCID guarantees support for at least three years from the release date. In addition, we give 12 months notice before retiring the oldest major version, and send periodic reminder emails to those members still using it during the notice period. New major versions are required whenever we make breaking changes to our metadata schema and are signified by an increment in the major version number. ORCID releases a new major API version every 2-4 years.
In exceptional circumstances, ORCID may consider extending the 12 month retirement period when a new major API version is released, but this requires ORCID to invest additional resources in maintenance work, with a consequential impact on other activities such as new development and support. ORCID reserves the right to charge extra fees for continued use of a retired API version beyond the retirement date in order to help offset the additional costs incurred.
ORCID has an incremental API deprecation policy that allows us to evolve our API offerings and respond to community needs between major releases. This means that ORCID may make non-breaking changes to the current API version’s controlled vocabularies and metadata fields.
- Users of the most recent API version are free to ignore these changes, but should be aware that they could be made
- Users of the previous API version will not receive data that cannot be modeled in their version
An example at the time of writing is the introduction of the CREDIT contributor role taxonomy into the v3.0 API. Once live, v2.x integrations will slowly lose visibility of contributor roles as more and more researchers and integrations adopt CREDIT. V2.x users won’t break, but they will receive less rich metadata as time passes.
When developing a new major API version it is normal for ORCID to produce ‘release candidate’ versions. These are aimed at integrators who are able to upgrade in a timely manner once the full version of the API is released. Expected lifetime of a release candidate is at most 12 months from the release of the major version it was developed for.
We advise integrators to follow the Robustness Principle (aka Postel’s law) when making use of the ORCID API.
Background
ORCID has slowly evolved it’s API from its humble beginnings.
API v1.x (Launch ~2012 together with the registry) attempted to return all metadata about researchers and their activities in a single API response. Integrators were required to modify this metadata and send it back in its entirety in order to add new items or update existing ones. This was a reasonable first attempt, but did not scale and making additions and updates was a painful task. (Retired March 2018)
API 2.x (Released Feb 2017) split our API into sections; works, affiliations, funding, biography etc. It was a big step forward and enabled both ourselves and our clients to manage large records much easier. However, much of our validation and controlled vocabularies were hard coded in the schema, making it difficult to respond to change
API 3.x (Released May 2019) added new sections to the record such as research resources, simplified the schema structure and provided ORCID with additional flexibility. It moved much of the validation from the schema into our servers, which has enabled us to fix issues and add new identifier types without releasing further versions of the API.
Releasing a new major API is a huge undertaking – years of developer effort are required to create it, and years more are required by our members to upgrade their integrations. For this reason we try to limit the changes we make. However, there are some changes we’d like to make in order to best serve the community.
Our job is to work out when we have a critical mass to release a new version of the API, or to work out ways of updating our existing APIs without breaking existing integrations.