July marks the fifth month since we released ORCID API v2.0, and we’re delighted to report that many users of the Public and Member API have already upgraded or are in the process of doing so. To encourage those of you who haven’t yet started your upgrade, we’d like to highlight some of the v2.0 features that will simplify your workflows, reduce transfer file sizes, and make your ORCID integration work better for you and your users alike.
Fewer scopes, less confusion
Our old API enabled you to request a lot of permissions from users: permission to create items in a section, to read that same section, and update it. Requesting separate permissions for each section resulted in a list of requests that confused users.
In API v2.0 we’ve consolidated our scopes into three, which allow you to request read (limited) and update access to all sections of the ORCID record.
Still have those tokens at the older permissions? Don’t worry – they’ll continue to work at the access levels for which they were originally issued. But you may want to build in a workflow to request that users refresh their permissions if your upgraded system has new features involving access to other sections of their record.
Read and update by item
Using previous versions of the API, if your system needed to add new single work on a record to which you had added multiple works, then it had to update the entire works section, including the new work and all previously added works. As a result, updating a single item on a record involved sending a potentially large file of other items which had no changes, or losing all items in that section, or even the entire record.
v2.0 has simplified this process by managing items on an individual basis. Your system can add a single work to an ORCID record, and then edit or delete that single work. This is done by implementing put codes for individual items on the ORCID Registry. For example, if your system adds a new employment affiliation to an ORCID record, the ORCID API returns a confirmation message along with the put code that your system can use to update or delete that item only. In general, only one item can be added, edited, or deleted at a time on an ORCID record. The sole exception is works, which for many researchers make up the bulk of their ORCID record. API v2.0 allows your systems to read up to 50 works at a time, and to add up to 100 works at a time. Editing or deleting works must still be done on an item basis.
Put codes are retroactive: items added in 1.2 and earlier have all been assigned put codes. As you work to upgrade your system for v2.0, remember to add a field for its corresponding put code. You can query an ORCID record to get the put codes of any items your system has added to the Registry, and update your database accordingly so you’ll be able to update them in the future as needed.
Read records faster
API v2.0, like the previous API, allows your system to read a single section or the entire record in a single call. What returns won’t be all data on a record but rather a summary view of the three sections which tend to be the largest on ORCID records: works, funding, and peer reviews.
Whether your system reads the full record or a single section, the summary view of these activities is displayed. The summary contains limited information: the works summary, for example, returns only the work title, type, date, its unique identifiers and their relationship to the work, the display index for each version of the item (if there are multiple versions), the source (the user or API client) and corresponding put code for each version of the item.
Summary views reduce file sizes and transfer times, reducing the potential strain on our system and yours, and making updates faster.
And so much more!
There’s a lot more in v2.0 to be happy about: flexible support for external identifiers, adding peer review activities, clearer grouping of multiple versions of activities, greater search results by default, and more.
Want to learn more? Join us! Each month we hold webinars in multiple time zones and languages, and for the rest of the year we will be discussing upgrading to API v2.0. Check our listings for the next one, or contact us to learn more.
Have you already upgraded to API v2.0? Let us know your experience!
