I’m often asked how ORCID manages to continually update the Registry to add new features, but still support the many enterprise-level systems owned and operated by ORCID Member organizations that use our APIs. The bottom line answer is flexibility. But, of course, it a bit more involved than that.
A little history
When we first launched in October 2012 we started out with API version 1.0.1. (Our prior prototype was version 1.0.) As you can imagine, during that first year we made many enhancements and added important new functionality, such as the ability to connect funding and affiliations to an ORCID Record. For each of these improvements we maintained backward compatibility, enabling organizations to update at their leisure. A year (and 23 updates!) later, we found that we were actively supporting 23 versions of our API. This required substantial staff resources to manage, and meant we had less time to add more of the features and improvements that our members and users sought. Worse still, nearly all API users were using version 1.0.7 or earlier, meaning that they weren’t benefiting from the new features we were implementing and supporting. Clearly this process wasn’t working well for anyone!
Focusing our approach
In November 2013 we developed an approach with the following goals:
- Keep the number of simultaneously-supported APIs to a manageable level for our small team.
- Provide better information to API users about which are the major and minor API updates.
- Serve API users that would like to have access to the latest updates and functionality, and those who require longer-horizon, enterprise-stable APIs.
- Enable flexibility for API users who are actively migrating to newer versions, though need extra support or time for the transition.
The Enterprise-Stable API
We now release a new, enterprise-stable API version once per year, generally in January. This version includes all of the new functionality, updates and improvements from the previous year.
- While the previous enterprise-stable version is still functional, it is considered to be “deprecated.”
- API users are informed 3-6 months ahead of the sunset date of the differences between the two versions, and are provided documentation and support to update their system. We also provide a notice to our technical contacts who have built an integration with the member API.
- After a period of time, the old version is “sunset,” after which it is no longer actively supported. Eventually the old version will no longer work.
- The amount of time when both versions are actively supported varies depending on the extent of the changes, and the effort required to make an update.
- We are committed to our members. We ALWAYS ensure that they have successfully migrated to the new version before discontinuing support for a deprecated API version.
The Innovation API
For our members that want earlier access to new features and improvements, we provide more frequent release candidate APIs that include the latest innovations.
- These versions provide an early view of the updates likely in the next enterprise-stable release.
- They include functionality we are testing, and enable API users to try out new functionality earlier.
- Release candidates are generally unsupported and have limited documentation. The ORCID development team is very interested in working collaboratively with members using release candidates to improve provisional functionality.
We provide details about current versions, dates when changes are happening, and more in our version documentation. We also recommend that anyone using the API become a member of the API Users Group where we share the latest information about the APIs.