ORCiD-Workshop: Die ORCiD-API

Die ORCiD-API

• Klassisch: HTTP, ReST, JSON (oder XML).
• Man muß v2.0 benutzen, alles andere wird bald abgeschaltet.
• Traffic drosseln – die ORCiD-Server sind nicht sehr potent. Maximal 24 Publikationen pro Sekunde, maximal vier Verbindungen gleichzeitig. Mehrere hundert Papers während des Requests hochzuladen geht also nur schlecht. Zumal man parallele Prozesse beachten muß.
• HTTP 5xx ist ganz gerne mal ein Client-Fehler.
• Die ORCiD-Mailingliste ist sehr hilfreich, aber die große Zeitverschiebung bei kritischen Schritten berücksichtigen.

Voraussetzungen

Man benötigt stets eine Client-ID und ein Client-Secret. Bekommt man von
ORCID.

• Auch für die Sandbox wird das benötigt.
• Auch für die „Public API“ wird das benötigt.

Unsere Konfiguration:

ORCID_CLIENT_ID = APP-****************
ORCID_CLIENT_SECRET = ********-****-****-****-************
SECRET_KEY = **************************************************
ORGANIZATION_NAME_REGEX = (Forschungszentrum|research center|research centre)\\s+j(ü|u|ue)lich
ORCID_AFFILIATION = {\"name\": \"Forschungszentrum Jülich\", \
                     \"address\": {\"city\": \"Jülich\", \
                                 \"region\": \"Nordrhein-Westfalen\", \
                                 \"country\": \"DE\"}, \
                     \"disambiguated-organization\": \
                     {\"disambiguated-organization-identifier\": \"28334\", \
                      \"disambiguation-source\": \"RINGGOLD\"}}

OAuth 2

Anmerkungen zur Implementierung

„State“ ist bei uns das Tupel (Nutzer-ID, Nutzer-ID || SECRET, Redirect-URL).

Das Access-Token muß sicher gespeichert werden. Verschlüsselt, aber nicht als
Hash. Bei uns: Mehrfach genutztes One-Time-Pad (räusper).

Nach erfolgreichem OAuth 2 findet Authorisierung bei jedem HTTPS-Request wie
folgt statt:

Authorization type: Bearer
Access token: <Access-Token für diesen Nutzer>

Wenn es nicht um das Profil einen bestimmten Nutzers geht: Client credientials
(client_id und client_secret) werden bei POST/PUT im Body übergeben, sonst
nur client_id im Query String.

Webserver

Demo

#!/usr/bin/python3

import requests, subprocess, json

response = requests.post(
    "https://orcid.org/oauth/token",
    data={"client_id": open("id").read(),
          "client_secret": open("secret").read(),
          "grant_type": "authorization_code",
          "code": subprocess.check_output(["ssh_zb", "cat", "/tmp/bronger_code"]).decode(),
          "redirect_uri": "https://juser.fz-juelich.de/orcid"
    })

result = json.loads(response.text)
print("\nORCiD: {}\nAccess-Token: {}".format(result.get("orcid"), result.get("access_token")))

Wichtige Endpunkte

• POST https://api.orcid.org/oauth/token: Um einen Authorization-Code in ein Access-Token umzutauschen.
• GET https://api.orcid.org/v2.0/<ORCiD-ID>/activities: Um alle „Aktivitäten“ eines Nutzers in einem Rutsch zu bekommen. Vor allem die Veröffentlichungen und die Affiliation.
• POST https://api.orcid.org/v2.0/<ORCiD-ID>/employment: Um eine Affiliation zu einem Nutzerprofil hinzuzufügen.

Dabei im HTTP-Header:

Accept: application/orcid+json
Content-Type: application/orcid+json

… oder halt XML, wenn einem das lieber ist.

Wichtige Endpunkte II

• POST https://api.orcid.org/v2.0/<ORCiD-ID>/work: Um eine Veröffentlichung zu einem Nutzerprofil hinzuzufügen.
• PUT https://api.orcid.org/v2.0/<ORCiD-ID>/work/<put-code>: Um die Veröffentlichung <put-code> des Nutzerprofils zu updaten.

Struktur einer Affiliation

{"name": "Forschungszentrum Jülich",
 "address": {"city": "Jülich",
             "region": "Nordrhein-Westfalen",
             "country": "DE"},
 "disambiguated-organization":
 {"disambiguated-organization-identifier": "28334",
  "disambiguation-source": "RINGGOLD"}}

Das ist dann die Nutzlast des POST-Requests.

Die Ringgold-Nummer nutzen wir (neben einer Regex auf den Namen), um zu
detektieren, ob die Affiliation schon im Profil hinterlegt ist. (ORCiD-IDs für
Affiliations wären hier natürlich praktisch, sind aber erst in Planung seitens
ORCiD.)

Put-Codes

Put-Codes sind die nicht-geheime interne ID von Objekten in der
ORCiD-Datenbank.

Zwei Möglichkeiten, an die Put-Codes zu kommen:

• Beim Anlegen von Dingen in ORCiD selber speichern. Der Put-Code wird beim Anlegen nämlich zurückgegeben.
• Sich die bei Bedarf von ORCiD holen. Für Veröffentlichungen geht das so:

1. Alle Veröffentlichungen eines Nutzers holen.
2. source-client-id.uri muß mit der eigenen URI übereinstimmen.
3. SOURCE_WORK_ID enthält dann die eigene interne ID der Veröffentlichung.
4. Der Put-Code steht im Feld „put-code“.

Python-API

• Python hat ein eigenes ORCiD-Binding: github.com/ORCID/python-orcid
• Sehr gute Code-Qualität, mit Tests abgesichert.
• Wird aktiv von CERN-Leuten gewartet.

Beispiel:

import orcid
api = orcid.MemberAPI(ORCID_CLIENT_ID, ORCID_CLIENT_SECRET, sandbox=False)
publications = api.read_record_member(orcid_id, "activities", token)["works"]

Original-Dokumentation der ORCiD-API

• Ist ein wenig unübersichtlich.
• ORCiD nutzt Swagger, d.h. man kann im Browser einfach api.orcid.org/v2.0/ ansurfen.

Fehler, die man abfangen sollte

• Access-Token-Holen klappt nicht (wir versuchen das bis zu sechs Mal).
• Jedesmal, wenn Sachen im ORCiD-Profil geändert wurden: Authorisierung könnte entzogen worden sein.
• HTTP 409 nach einem PUT auf eine Veröffentlichung bedeutet: Veröffentlichung ist da, aber auf „privat“ gesetzt.
• Grundsätzlich ist der Fehlertext im Body der Response sehr hilfreich.

Thank you