Recording of Hub demo 31 May 2018

[jm.orc...@gmail.com]

A recording of the Hub demo of 31 May 2018 (using the API) is available at https://drive.google.com/drive/folders/0B9xSYAcL09d4UmZCWHpVMFRORXc (version 4_introduction_to_the_Hub_API_31May2018.mp4)

JIll

[Jason Gush]

As promised, here are the curl for use with test after an organisation's tech contact has asked us for access to the Hub API and registered their Hub App at https://test.orcidhub.org.nz/settings/credentials/, i.e, 

With those Hub client id and client secret, we can obtain a Hub access token that's good for 86400 seconds, i.e., 24 hours.

E.g. using the right curl for your OS and substituting your own credentials:

curl --header "Accept: application/json" --data "client_id=496fc8836a31cb6f32e6&client_secret=L6gjT_q4xzG6c8z1J2zNnUOEuoY&grant_type=client_credentials" "https://test.orcidhub.org.nz/oauth/token"

The result will be of the form:

{"access_token": "Kkv1YNSz1hbTGKQoHio7idxb3oLWPQ", "expires_in": 86400, "token_type": "Bearer", "scope": ""}

Taking that access token, you're able to address the Hub's endpoints to perform the tasks that otherwise require the Hub's UI, and some which cannot be performed in any other way, e.g., retrieve a User's ORCID access token.

Managing your users

• Retrieve a list of users, i.e. “Researchers” tab https://test.orcidhub.org.nz/admin/viewmembers/ with and without a date filter
• curl -H "Accept: application/json" -H "authorization: Bearer Kkv1YNSz1hbTGKQoHio7idxb3oLWPQ" "https://test.orcidhub.org.nz/api/v0.1/users"
• curl -H "Accept: application/json" -H "authorization: Bearer Kkv1YNSz1hbTGKQoHio7idxb3oLWPQ" "https://test.orcidhub.org.nz/api/v0.1/users?from_date=2018-05-10&to_date=2018-05-20"

• Check if a specific user exists for your organisation in the Hub,e.g., 'jagu04+orci...@gmail.com'; NB note the URL encoding of the search term
• curl -H "Accept: application/json" -H "authorization: Bearer Kkv1YNSz1hbTGKQoHio7idxb3oLWPQ" "https://test.orcidhub.org.nz/api/v0.1/users/jagu04%2Borcidtechcontact%40gmail.com"

• Retrieve ORCID API access token for specific user; NB not available through Hub UI
• curl -H "Accept: application/json" -H "authorization: Bearer Kkv1YNSz1hbTGKQoHio7idxb3oLWPQ"  "https://test.orcidhub.org.nz/api/v0.1/tokens/0000-0001-9357-7498"

Managing batch affiliation tasks

• Create (POST) an affiliation task, i.e. “Affiliations/Upload Affiliations” tab https://test.orcidhub.org.nz/load/researcher
• curl -H "accept: application/json" -H "authorization: Bearer Kkv1YNSz1hbTGKQoHio7idxb3oLWPQ" -H "Content-Type: application/json" -d "{ \"records\": [ { \"affiliation-type\": \"staff\", \"department\": \"API written employment dept\", \"email\": \"jagu04o...@mailinator.com\", \"end-date\":  \"2018-02-01\", \"start-date\": \"2017-02-01\", \"first-name\": \"Generic\", \"is-active\": false, \"role\": \"API written employment role\", \"last-name\": \"Contributor2\" }, { \"affiliation-type\": \"student\", \"department\": \"API written education dept\", \"email\": \"jagu04o...@mailinator.com\", \"end-date\":  \"2017-01-01\", \"start-date\": \"2016-01-01\", \"first-name\": \"Generic\", \"is-active\": false, \"role\": \"API written education role\", \"last-name\": \"Contributor2\" } ], \"task-type\": \"AFFILIATION\"}" "https://test.orcidhub.org.nz/api/v0.1/affiliations"

 

• Edit (PATCH) the task created, e.g., make the records active which is the same as the UI’s “With selected > Activate”; NB 1/ the curl above created a task with id 229 containing the items with ids 827 and 828 and these values are returned as a result of the curl.  2/ Items created with "is-active" true don't need this as they will be acted on by the Hub straight away.
• curl -X PATCH -H "accept: application/json" -H "authorization: Bearer Kkv1YNSz1hbTGKQoHio7idxb3oLWPQ" -H "Content-Type: application/json" -d "{\"id\":229,\"records\":[{\"id\":827,\"is-active\":true},{\"id\":828,\"is-active\":true}]}" "https://test.orcidhub.org.nz/api/v0.1/affiliations/229"

 

• Retrieve (GET) task result aka “Export as json”
• curl -H "accept: application/json" -H "authorization: Bearer Kkv1YNSz1hbTGKQoHio7idxb3oLWPQ" "https://test.orcidhub.org.nz/api/v0.1/affiliations/229"

 

• Replace (PUT) the task
• curl -X PUT -H "accept: application/json" -H "authorization: Bearer Kkv1YNSz1hbTGKQoHio7idxb3oLWPQ" -H "Content-Type: application/json" -d "{\"completed-at\":null,\"created-at\":\"2018-05-30T23:51:54\",\"expires-at\":null,\"expiry-email-sent-at\":null,\"filename\":\"2018-05-30T23:51:54\",\"id\":229,\"records\":[{\"affiliation-type\":\"staff\",\"city\":null,\"country\":null,\"department\":\"API written employment dept\",\"disambiguated-id\":null,\"disambiguated-source\":null,\"email\":\"jagu04o...@mailinator.com\",\"end-date\":\"2018-02-01\",\"external-id\":null,\"first-name\":\"Generic\",\"id\":827,\"is-active\":false,\"last-name\":\"Contributor2\",\"orcid\":null,\"organisation\":null,\"processed-at\":null,\"put-code\":null,\"role\":\"API written employment role\",\"start-date\":\"2017-02-01\",\"state\":null,\"status\":null},{\"affiliation-type\":\"student\",\"city\":null,\"country\":null,\"department\":\"API written education dept\",\"disambiguated-id\":null,\"disambiguated-source\":null,\"email\":\"jagu04o...@mailinator.com\",\"end-date\":\"2017-01-01\",\"external-id\":null,\"first-name\":\"Generic\",\"id\":828,\"is-active\":false,\"last-name\":\"Contributor2\",\"orcid\":null,\"organisation\":null,\"processed-at\":null,\"put-code\":null,\"role\":\"API written education role\",\"start-date\":\"2016-01-01\",\"state\":null,\"status\":null}],\"task-type\":\"AFFILIATION\",\"updated-at\":\"2018-05-30T23:51:54\"}" "https://test.orcidhub.org.nz/api/v0.1/affiliations/229"

 

• Remove (DELETE) the task aka clicking the trash icon on "Uploaded tasks" https://test.orcidhub.org.nz/admin/task/
• curl -X DELETE -H "accept: application/json" -H "authorization: Bearer Kkv1YNSz1hbTGKQoHio7idxb3oLWPQ" "https://test.orcidhub.org.nz/api/v0.1/affiliations/229"

Note with recent changes to the Hub, this is even easier to explore.  Now when you click "Authorize" on the Hub's Swagger UI it will automatically populate the client id and client secret for a registered Hub app, and handle the retrieval of a valid Hub access token.