Post on 16-Apr-2017
orcid.org
Contact Info: p. +1-301-922-9062 a. 10411 Motor City Drive, Suite 750, Bethesda, MD 20817 USA
What’s new in v2?The latest on ORCID API v2 & what it means for you
Simeon WarnerDirector of IT for Library Linked Data and Repository
ArchitectureCornell University Library
orcid.org/0000-0002-7970-7855
Why v2.0Hooray, we’re launching a new API!Why? We’ll talk about that in a moment.It’s different from the current APICurrent API users: Some changes will be needed.We’ll talk about that, too.But it’s got great features that willmake things better for everyone!Ok then, let’s get to it.
2
Why v2.0A brief history of ORCID…
• Nov 2012: ~26, 000 iDs + tiny records
3
NOV2012
<orcid-profile><given-names>Josiah</given-names><family-name>Carberry</family-name><biography>Bio</biography><email>j.carberry@orcid.org</email><orcid-works>
<orcid-work><identifier-type>doi</identifier-type>
<identifier-id>10.1087/20120404</identifier-id>
</orcid-work></orcid-works>
</orcid-profile>
Why v2.0Things have changed.
• Now: ~2.6million iDs + MASSIVE records
4
OCT2016
Why v2.0Today ORCID includes:
• 15,356,999 works• 2,014,460 affiliation assertions• 207,048 funding items• 35,722 records with over 100 works• 81 member organizations posting works
5
Why v2.0
FANTASTIC! ...But API v1.2 just can’t keep up anymore.
HELLO v2.0! ...The ORCID API ofthe
6
Reading ORCID Records
7
v1.2Read/write in big chunks
v2.0Read/write in tasty,
bite-sized pieces
Photo credit theimpulsivebuy CC BY-SA 2.0 https://flic.kr/p/tbrwZV Photo credit Andrea Westmoreland CC BY-SA 2.0 https://flic.kr/p/4GQ7pg
v1.2 Reading ORCID Records
8
v1.2: Reading record http://orcid.org/0000-0001-5109-3700
v2.0 Reading ORCID Records
9
{"last-modified-date": {"value": 1462157547720},"name": {"created-date": {"value": 1460757617078},"last-modified-date": {"value": 1460757617078},"given-names": {"value": "Josiah"},"family-name": {"value": "Carberry"},"credit-name": null,"source": null,"visibility": "PUBLIC","path": null},"other-names": {"last-modified-date": {"value": 1462157547720},"other-name": [{"created-date": {"value": 1462157351411},"last-modified-date": {"value": 1462157547720},"source": {"source-orcid": {"uri": "http://orcid.org/0000-0002-1825-0097","path": "0000-0002-1825-0097","host": "orcid.org"},"source-client-id": null,"source-name": {"value": "Josiah Carberry"}},"content": "Josiah Stinkney Carberry","visibility": "PUBLIC","path": "/0000-0002-1825-0097/other-names/732317","put-code": 732317,"display-index": 3},{"created-date": {"value": 1446663146889},"last-modified-date": {"value": 1462157547720},"source": {"source-orcid": {"uri": "http://orcid.org/0000-0002-1825-0097","path": "0000-0002-1825-0097","host": "orcid.org"},"source-client-id": null,"source-name": {"value": "Josiah Carberry"}},"content": "J. Carberry","visibility": "PUBLIC","path": "/0000-0002-1825-0097/other-names/565981","put-code": 565981,"display-index": 2},{"created-date": {"value": 1462157351418},"last-modified-date": {"value": 1462157547720},"source": {"source-orcid": {"uri": "http://orcid.org/0000-0002-1825-0097","path": "0000-0002-1825-0097","host": "orcid.org"},"source-client-id": null,"source-name": {"value": "Josiah Carberry"}},"content": "J. S. Carberry","visibility": "PUBLIC","path": "/0000-0002-1825-0097/other-names/732318","put-code": 732318,"display-index": 1}],"path": "/0000-0002-1825-0097/other-names"},"biography": {"created-date": {"value": 1460757617080},"last-modified-date": {"value": 1460757617080},"content": "Josiah Carberry is a fictitious person. This account is used as a demonstration account by ORCID, CrossRef and others who wish to demonstrate the interaction of ORCID with other scholarly communication systems without having to use a real-person's account.\r\n\r\nJosiah Stinkney Carberry is a fictional professor, created as a joke in 1929. He is said to still teach at Brown University, and to be known for his work in \"psychoceramics\", the supposed study of \"cracked pots\". See his Wikipedia entry for more details.","visibility": "PUBLIC","path": "/0000-0002-1825-0097/biography"},"path": "/0000-0002-1825-0097/personal-details"}
{"last-modified-date":{"value":1462157635636},"keyword":[{"created-date":{"value":1462157617244},"last-modified-date":{"value":1462157635636},"source":{"source-orcid":{"uri":"http://orcid.org/0000-0002-1825-0097","path":"0000-0002-1825-0097","host":"orcid.org"},"source-client-id":null,"source-name":{"value":"JosiahCarberry"}},"content":"psychoceramics","visibility":"PUBLIC","path":"/0000-0002-1825-0097/keywords/434187","put-code":434187,"display-index":3},{"created-date":{"value":1462157414545},"last-modified-date":{"value":1462157635636},"source":{"source-orcid":{"uri":"http://orcid.org/0000-0002-1825-0097","path":"0000-0002-1825-0097","host":"orcid.org"},"source-client-id":null,"source-name":{"value":"JosiahCarberry"}},"content":"ionianphilology","visibility":"PUBLIC","path":"/0000-0002-1825-0097/keywords/434184","put-code":434184,"display-index":2}],"path":"/0000-0002-1825-0097/keywords"}
{"last-modified-date":{"value":1462157645967},"researcher-url":[{"created-date":{"value":1446663146890},"last-modified-date":{"value":1462157645967},"source":{"source-orcid":{"uri":"http://orcid.org/0000-0002-1825-0097","path":"0000-0002-1825-0097","host":"orcid.org"},"source-client-id":null,"source-name":{"value":"JosiahCarberry"}},"url-name":"BrownUniversityPage","url":{"value":"http://library.brown.edu/about/hay/carberry.php"},"visibility":"PUBLIC","path":"/0000-0002-1825-0097/researcher-urls/568395","put-code":568395,"display-index":2},{"created-date":{"value":1446663146889},"last-modified-date":{"value":1462157645967},"source":{"source-orcid":{"uri":"http://orcid.org/0000-0002-1825-0097","path":"0000-0002-1825-0097","host":"orcid.org"},"source-client-id":null,"source-name":{"value":"JosiahCarberry"}},"url-name":"WikipediaEntry","url":{"value":"http://en.wikipedia.org/wiki/Josiah_Carberry"},"visibility":"PUBLIC","path":"/0000-0002-1825-0097/researcher-urls/568394","put-code":568394,"display-index":1}],"path":"/0000-0002-1825-0097/researcher-urls"}
Personal Details
Keywords
Websites
v2.0 Reading ORCID Records
10
Sections returned in 2.0Activities /activities
All biographical information /person
Address /address
Email /email
External Identifiers /external-identifiers
Keywords /keywords
Other names /other-names
Names and biography /personal-details
Websites /researcher-urls
v2.0 Reading ORCID Records
11
Read by sectionEx: Read activities ection curl -H 'Content-Type: application/orcid+xml' -H 'Authorization: Bearer f3f932ad-d645-4cdb-a6eb-be1beeb50fea' 'https://api.sandbox.orcid.org/v2.0_rc3/0000-0002-6945-7290/activities’ -L -i -k
...or use a put-code to read a single itemEx: Read a single workcurl -H 'Content-Type: application/vdn.orcid+xml' -H 'Authorization: Bearer 2e5b87f0-57c9-44a8-96d3-3bae005598a7' -X GET 'https://pub.sandbox.orcid.org/v2.0_rc3/0000-0002-6945-7290/work/708456' -i
See: https://github.com/ORCID/ORCID-Source/tree/master/orcid-model/src/main/resources/record_2.0_rc3
Updating ORCID Records
12
v1.2Update everything
v2.0Update/delete individual
items
Photo credit teadrinker https://flic.kr/p/4xpuTb CC BY ND Photo credit Christo de Klerk https://flic.kr/p/8LowuV CC BY NC
v2.0 Updating ORCID Records
13
Update and Delete● Update/delete items with your client ID as the source● Need token with /activities/update scope● URL format: https://api.sandbox.orcid.org/v2.0_rc3/[ORCID]/[ACTIVITY-TYPE]/[PUT-CODE]
Update a work:curl -i -H 'Content-type: application/orcid+xml' -H 'Authorization: Bearer dd91868d-d29a-475e-9acb-bd3fdf2f43f4' -d '@work-updated.xml' -X PUT 'https://api.sandbox.orcid.org/v2.0_rc3/0000-0002-1306-4180/work/12345'
Delete a work: curl -i -H 'Content-type: application/orcid+xml' -H 'Authorization: Bearer dd91868d-d29a-475e-9acb-bd3fdf2f43f4' -X DELETE 'https://api.sandbox.orcid.org/v2.0_rc3/0000-0002-1306-4180/work/12345'
See: https://github.com/ORCID/ORCID-Source/tree/master/orcid-model/src/main/resources/record_2.0_rc3
Permissions
14
v1.2lots of overlapping
scopesv2.0
4 scopes for all access
Photo credit Jenny Mackness https://flic.kr/p/qCEVha CC BY NC SA
Photo credit mewewering https://pixabay.com/p-615239 CC0
v1.2 Permissions
Requesting authorization with all 1.2 scopes
15
v2.0 Permissions
v2.0 Scopes (just 4!)
See: https://github.com/ORCID/ORCID-Source/tree/master/orcid-model/src/main/resources/record_2.0_rc3
16
/authenticate get a user’s ORCID iD/read-limited read public and limited information
from an ORCID record/activities/update write, update, and delete items in
the activities section/orcid-bio/update write, update, and delete items in
the biography section
Activities Summary
17
v1.2all the details for each
activityv2.0activities summary
Photo credit j e r e m y https://flic.kr/p/wgSYTz CC BY NC ND
Photo credit Aminul Islam Sajib https://flic.kr/p/mmuCPi CC BY NC ND
v1.2 Activities
18
A single work in v1.2
v2.0 Activities Summary
19
work summary in 2.0
v2.0 Activities Summary
20
Activities Summary● Just the basics about each activity
○ title○ type○ dates○ identifiers○ creation/modification/source metadata
Get a summary:curl -i -H "Accept: application/orcid+xml" -H 'Authorization: Bearer dd91868d-d29a-475e-9acb-bd3fdf2f43f4' 'https://api.sandbox.orcid.org/v2.0_rc3/0000-0002-1306-4180/activities'
See: https://github.com/ORCID/ORCID-Source/tree/master/orcid-model/src/main/resources/record_2.0_rc3
Ordering
21
v1.2no order
v2.0display index & groups
Photo credit hjhipster https://flic.kr/p/7guADn CC BY NCPhoto credit April Scott https://flic.kr/p/5EBaJb CC BY NC ND
v1.2 Ordering
22
v1.2: Keyword order in the UI vs. API
v2.0 Ordering
23
v2.0 Keyword
v2.0 Ordering
24
v2.0 Display Order
See: https://github.com/ORCID/ORCID-Source/tree/master/orcid-model/src/main/resources/record_2.0_rc3
Section Display index is...Bio Order of items set by the
user (highest number first)
Activities For items with the same external ID (which are grouped in the interface and API), order of an item within its group (highest number is preferred version)
All 0 until sorted by the user
External Identifiers
25
v1.2external identifiers
v2.0robust external
identifiers
Photo credit sj leiw https://flic.kr/p/5SiHP7 CC BY NC ND Photo credit richardghawley https://flic.kr/p/6gmVqB CC BY ND
External Identifiers
26
ISSN identifier in v1.2
ISSN identifier in v2.0
←Only default links
Can’t tell if the identifier should be used when creating groups ↓
v2.0 External Identifiers
27
New identifier fieldsID Relationship<common:external-id-relationship> indicates if the identifier is for the item itself (self) or a larger whole (part-of)
ID URL<common:external-id-url> specifies where the identifier links out to
See: https://github.com/ORCID/ORCID-Source/tree/master/orcid-model/src/main/resources/record_2.0_rc3
Source Info
28
v1.2source sometimes...
v2.0source, created date,
modified date for everything
Photo credit Wolfgang Korn Photo credit Brian Moore https://flic.kr/p/cMiPR CC BY SA
v1.2 Source Info
29
<orcid-history><creation-method>Direct</creation-method><submission-date>2016-07-13T22:24:21.651Z</submission-date><last-modified-date>2016-10-05T16:30:57.131Z</last-modified-date><claimed>true</claimed><verified-email>false</verified-email><verified-primary-email>false</verified-primary-email></orcid-history>
v1.2 can tell you something on this record changed today, but you’ll need to compare it to an older version to find out
what
v2.0 Source Info
30
Standardized Source InfoItems<common:created-date><common:last-modified-date><common:source>
Groups<common:last-modified-date>
Sections<common:last-modified-date>
Last modified is hierarchical: when an item changes the dates on the group and section are updated as wellSee: https://github.com/ORCID/ORCID-Source/tree/master/orcid-model/src/main/resources/common_2.0_rc3
Error Messages
31
v1.2human readable errors,
sometimes
v2.0detailed error messages
& referencePhoto credit Matthew https://flic.kr/p/5AEXKV CC BY NC ND Photo credit Jessica May Oyler
v1.2 Error Messages
32
<error-desc>javax.xml.bind.UnmarshalException - with linked exception:[org.xml.sax.SAXParseException; lineNumber: 1; columnNumber: 44; The processing instruction target matching "[xX][mM][lL]" is not allowed.]</error-desc>
<error-desc>com.sun.jersey.api.MessageException: A message body reader for Java class org.orcid.jaxb.model.message.OrcidMessage, and Java type class org.orcid.jaxb.model.message.OrcidMessage, and MIME media type application/vdn.orcid was not found.</error-desc>
<error-desc>javax.xml.bind.UnmarshalException: unexpected element (uri:"", local:"orcid-message"). Expected elements are <{http://www.orcid.org/ns/orcid}activities-visibility-default>,<{http://www.orcid.org/ns/orcid}address>,<{http://www.orcid.org/ns/orcid}affiliation>,<{http://www.orcid.org/ns/orcid}affiliation-city>,<{http://www.orcid.org/ns/orcid}affiliation-country>,<{http://www.orcid.org/ns/orcid}affiliation-region>,<{http://www.orcid.org/ns/orcid}affiliation-type>,<{http://www.orcid.org/ns/orcid}agency-name>,<{http://www.orcid.org/ns/orcid}agency-orcid>,<{http://www.orcid.org/ns/common}amount>,<{http://www.orcid.org/ns/orcid}amount>,<{http://www.orcid.org/ns/orcid}application-name>,<{http://www.orcid.org/ns/orcid}application-orcid>,<{http://www.orcid.org/ns/orcid}application-summary>,<{http://www.orcid.org/ns/orcid}application-website>,<{http://www.orcid.org/ns/orcid}applications>,<{http://www.orcid.org/ns/orcid}approval-date>,<{http://www.orcid.org/ns/orcid}assignee>,<{http://www.orcid.org/ns/orcid}assignee-name>,<{http://www.orcid.org/ns/orcid}assignee-orcid>,<{http://www.orcid.org/ns/notification}authorization-url>,<{http://www.orcid.org/ns/orcid}biography>,<{http://www.orcid.org/ns/orcid}claimed>,<{http://www.orcid.org/ns/orcid}completion-date>,<{http://www.orcid.org/ns/orcid}contact-details>,<{http://www.orcid.org/ns/common}contributor>,<{http://www.orcid.org/ns/funding}contributor>,<{http://www.orcid.org/ns/orcid}contributor>,<{http://www.orcid.org/ns/common}contributor-attributes>,<{http://www.orcid.org/ns/orcid}contributor-attributes>,<{http://www.orcid.org/ns/common}contributor-email>,<{http://www.orcid.org/ns/orcid}contributor-email>,<{http://www.orcid.org/ns/common}contributor-orcid>,<{http://www.orcid.org/ns/orcid}contributor-orcid>,<{http://www.orcid.org/ns/orcid}contributor-role>,<{http://www.orcid.org/ns/orcid}contributor-sequence>,<{http://www.orcid.org/ns/funding}contributorAttributes>,<{http://www.orcid.org/ns/funding}contributors>,<{http://www.orcid.org/ns/common}country>,<{http://www.orcid.org/ns/orcid}country>,<{http://www.orcid.org/ns/common}created-date>,<{http://www.orcid.org/ns/orcid}created-date>,<{http://www.orcid.org/ns/orcid}creation-method>,<{http://www.orcid.org/ns/common}credit-name>,<{http://www.orcid.org/ns/orcid}credit-name>,<{http://www.orcid.org/ns/common}day>,<{http://www.orcid.org/ns/orcid}day>,<{http://www.orcid.org/ns/orcid}deactivation-date>,<{http://www.orcid.org/ns/orcid}delegate-summary>,<{http://www.orcid.org/ns/orcid}delegation>,<{http://www.orcid.org/ns/orcid}delegation-details>,<{http://www.orcid.org/ns/orcid}department-name>,<{http://www.orcid.org/ns/orcid}deprecated>,<{http://www.orcid.org/ns/orcid}deprecated-date>,<{http://www.orcid.org/ns/orcid}developer-tools-enabled>,<{http://www.orcid.org/ns/orcid}disambiguated-affiliation-identifier>,<{http://www.orcid.org/ns/common}disambiguatedOrganization>,<{http://www.orcid.org/ns/orcid}disambiguation-source>,<{http://www.orcid.org/ns/education}education>,<{http://www.orcid.org/ns/orcid}email>,<{http://www.orcid.org/ns/employment}employment>,<{http://www.orcid.org/ns/orcid}encrypted-password>,<{http://www.orcid.org/ns/orcid}encrypted-security-answer>,<{http://www.orcid.org/ns/orcid}encrypted-verification-code>,<{http://www.orcid.org/ns/orcid}end-date>,<{http://www.orcid.org/ns/notification}external-id>,<{http://www.orcid.org/ns/orcid}external-id-common-name>,<{http://www.orcid.org/ns/orcid}
v2.0 Error Messages
33
v2.0 Error message anatomy
Example:<error xmlns="http://www.orcid.org/ns/error">
<response-code>400</response-code><developer-message>javax.ws.rs.WebApplicationException:
javax.xml.bind.UnmarshalException - with linked exception:[org.xml.sax.SAXParseException; lineNumber: 1; columnNumber: 1779; cvc-complex-type.2.4.a: Invalid content was found starting with element 'common:external-id-relationship'. One of '{"http://www.orcid.org/ns/common":external-id-value}' is expected.]</developer-message>
<user-message>ORCID could not process the data, because they were invalid.</user-message>
<error-code>9001</error-code><more-info>http://members.orcid.org/api/api-error-codes</more-info></
error>See: http://members.orcid.org/api/api-error-codes
<response-code> HTML status code<developer-message> Details about what went wrong<user-message> Friendly message you should display to users<error-code> ORCID code for more info on how to fix the
error
Sacred Fields
34
v1.2overwrite user data
v2.0fields are sacred to user
Photo credit Jeff Warren https://flic.kr/p/z6K1L CC BY SA Photo credit Hans Hillewaert https://commons.wikimedia.org/wiki/File:Rosetta_Stone.JPG CC BY SA
v1.2 Sacred Fields
35
v1.2: Names can be overwritten via API...by members with bad data in their system
v2.0 Sacred Fields
36
Some fields can only be edited by the user● <personal-details:given-names>● <personal-details:family-name>● <personal-details:credit-name>● <person:biography>
Generally, fields that can only be edited by users are non-repeatable, except...Email field cannot be edited! (security feature)
See: https://github.com/ORCID/ORCID-Source/tree/master/orcid-model/src/main/resources/record_2.0_rc3
XSD
37
v1.2One messy XSD
v2.0multiple pieces &
consistency
Photo credit Bomba Rosa https://flic.kr/p/eQ8ioT CC BY ND Photo credit proacguy1 https://commons.wikimedia.org/w/index.php?curid=34109180 CC BY SA
XSD
38
<work-external-identifiers> <work-external-identifier>
<work-external-identifier-type>doi</work-external-identifier-type><work-external-identifier-id>10.1087/20120404</work-external-identifier-id>
</work-external-identifier></work-external-identifiers>
<funding-external-identifiers> <funding-external-identifier>
<funding-external-identifier-type>grant_number</funding-external-identifier-type>
<funding-external-identifier-value>1234</funding-external-identifier-value><funding-external-identifier-url>www.funding.com/1234</funding-external-
identifier-url> </funding-external-identifier></funding-external-identifiers>
<external-identifiers> <external-identifier>
<external-id-common-name>Scopus Author ID</external-id-common-name><external-id-reference>6602258586</external-id-reference><external-id-url>http://www.scopus.com/inward/authorDetails.url?
authorID=6602258586</external-id-url> </external-identifier></external-identifiers>
Three different ways of recording an identifier in 1.2
v1.2 XSD
39
Stuff that’s in the 1.2 XSD
Internal fields
Stuff we never supported
Items we stopped using
v2.0 XSD
40
1.2: Same elements in multiple XSDs Name spaces used in the XML document
2.0: Common XSD for repeated elements● Item metadata● Source● External identifiers● Dates● Organizations● Language● URLs● ORCID iDs
See: https://github.com/ORCID/ORCID-Source/tree/master/orcid-model/src/main/resources/common_2.0_rc3
Peer Review
41
v2.0Peer review!
Photo credit Photo credit AJC1 CC BY-SA 2.0 https://flic.kr/p/bgepei
v2.0 Peer ReviewNew activities section: Peer review● Grouped by journal, organization, etc (source
adding the item decides)● Minimal metadata required - OK for closed
reviews● API only - users can’t add/edit peer review
activities
See: http://members.orcid.org/api/peer-review-getting-started
42
43
Thanks!Questions?
Simeon simeon.warner@cornell.edu (presenter)
Catalina c.wilmers@orcid.org (deck creator)
ORCID Support support@orcid.org