In this interview Rob Peters, ORCID’s Director of Technology, introduces ORCID’s new API – launched on February 14, 2017
Before we start talking about the new API, can you tell us a bit about ORCID’s Technical Team and your role as Director?
At first glance, the ORCID team looks much like any other technical team. We have five developers, a server administrator, a quality assurance analyst, and, of course, a manager (me). However, where it gets interesting is our different geographical, cultural, and work backgrounds. Three of us are US-based, three are based in Costa Rica, and two are based in the UK, so geographically we get a lot of perspective. In addition, some of us are from traditional software consulting, others come from the publishing industry, “Silicon Valley” startups, and library sciences.
My personal role as Director of Technology is managing the day-to-day software development. That boils down to helping my team communicate with each other and the rest of the organization, as well as managing which tasks the team takes on (and which get put off). I also get the opportunity to have a lot of input on higher-level strategic decisions ORCID makes.
Moving onto API version 2.0 – why do we – ORCID, as well as the ORCID community – need this upgrade?
The first ORCID API, which launched in October 2012, was inevitably based on many assumptions that later proved wrong and/or required refining. To better serve the research community, we have to continuously examine those assumptions. Using feedback, asking questions, and looking at evidence that wasn’t available before we launched has given us new insights into what the ORCID API should and shouldn’t be. As you’ll see from my answer to the next question, Version 2.0 represents a major break from the assumptions that 1.0 was built on, while still being pragmatic enough to provide continuity between the two APIs.
What are the main differences between 1.2 and 2.0 and how will they benefit members?
In developing 2.0, we wanted to both address the roadblocks that members have been hitting with 1.2 and also introduce new functionality that we know the community wants.
So as well as tackling known issues such as scalability in managing hyper-authored publications, and challenges with implicit behavior that were causing confusion for members, we have also added new functionality to support peer review recognition, improved notifications for users, and the ability to support almost any persistent identifier.
To explain why some of these changes were needed, I’m going to get a bit technical. Before we set out to code a single new line, we made a list of things we wanted to see improved, with the following “manifesto”:
- Stop thinking of the ORCID record as a monolithic (large single) document. Multiple institutions writing to an ORCID record means recognizing the record is multi-tenant. Additionally, researchers often produce such vast amounts of research that even summaries of it won’t fit in a monolithic document.
- Simplified scopes. The granularity of permissions scopes in the 1.0 API is overwhelming for all parties involved; simplifying them will make life easier for developers and users alike.
- Explicit RESTful behavior. Implicit behaviors are bad for implementers since they lead to unexpected behavior which, in turn, confuses end users. By using RESTful behavior, our new API avoids these problems.
- Shortest reasonable urls. A good example would be /works/1234 is better than /orcid-works/1234.
- Calls to list only return summaries. In order to make calling a record faster, API 2.0 only returns summaries for lists. Doing one call for every piece of information about a researcher doesn’t work for hyper-authored articles, where there are tens, hundreds, or even thousands of authors.
- Common names and structures for common elements. 2.0 enables us to make sure common elements in the XML/JSON have the same names.
- Error codes. We now include error codes in the response body when the error is not fully described by a standard HTTP code.
And what are the benefits for users?
At the end of the day, an API should be seamless to users. Unexpected 1.0 behaviour bubbles up and affects the user’s experience while at the same time frustrating the developers who are implementing the API. On a practical level the new API enables streamlining each section in the ORCID record to consistently provide application of visibility settings, source, and creation date for items in each section.
Will this affect the Public API as well? How?
Yes. Changes to the Member API and Public API are always in lockstep. Although we appreciate and rely on member support we also are committed to our larger vision “of a world where all who participate in research, scholarship, and innovation are uniquely identified and connected to their contributions across disciplines, borders, and time.” We see the Public API as a means of helping achieve that goal.
What do you think will be the main challenges in rolling out the new version, and what support will ORCID be providing?
The hardest issue is putting aside resources to do the work to upgrade. For some organizations it might be as little as a couple of days and other might require a full month. Regardless of the timeframe, don’t be afraid to reach out and ask for help, even for a little detail that is stopping your progress. Full documentation is available now on members.orcid.org and ORCID member organizations can also contact us. Posting to the API Users Forum can be useful, bringing in comments from across the ORCID community. I’m also a firm believer in being directly available, so feel to email me directly.
Who is currently using API 2.0 and what sort of feedback have they provided?
We put a lot of effort into making release candidates available in order to get feedback. CrossRef, Datacite, CERN, and PTCRIS are just a few of the ORCID members who’ve implemented a release candidate and provided feedback. In addition, several organizations have implemented peer review functionality using 2.0, including early adopters, the American Geophysical Union, F1000, and Publons. Feedback has included the usual “techie” suggestions such as names used in schema, endpoint naming, or debates about efficiency. Those kind of details can have big implications for members. However release candidates implementers also provide feedback from the researcher’s perspective, which we find invaluable.
How long will ORCID continue to support the old API?
We are aiming to sunset 1.2 in late 2017. Regardless of the sunset date, if you agree with ORCID’s mission and care about researchers interact with ORCID you’ll want to move to 2.0 now.
Anything else we should know about this change?
We hope 2.0 proves to be durable and we can focus on other parts of the ORCID technology stack for a good while!
For a fun and handy summary of API 2.0 features, see this slide deck!
