Web-API (nativ)

DeepGreen bietet eine (rudimentäre) REST-Schnittstelle an. Die aktuelle Version der DeepGreen REST API ist v1. Diese kann über die Web-Adresse https://www.oa-deepgreen.de/api/v1 angesprochen werden, z.B. mit dem Kommando curl in einer Shell (bash, tcsh, etc.):

$ curl -s [-X GET|POST|PUT|HEADER] https://www.oa-deepgreen.de/api/v1/...

Dabei werden in den nun nachfolgende Beispielen die ... ersetzt durch die konkreten REST-Resourcen validate, notification und routed der Web-API-Schnittstelle. Eine weitere, für die GUI-lose Bedienung von Repositorienkonten gedachte REST-Resource ist durch den Endpunkt config gegeben. Diese Resource ist insbesondere für Repositorienbetreiber, die eigene Skripte zur Verwaltung ihrer Konten entwickeln möchten. Sie ist hier der Vollständigkeit halber mit aufgeführt.

Im Folgenden soll der Übersichtlichkeit halber GET, POST, usw. für die gesamte, wie oben angegebene curl-Zeile geschrieben werden. Hier ein kleiner Überblick der möglichen Aufrufe in dieser Kurzform:

  • Aufruf : POST /validate

    Angabe von Metadaten durch “Incoming Notification JSON” (internes DeepGreen-Format)
    POST /validate?api_key=<api_key>
    Content-Type: application/json
    
    [Incoming Notification JSON]
    
  • Aufruf : POST /notification

    http-POST: Bündelung durch “Content-Type: multipart/form-data; ...
    POST /notification?api_key=<api_key>
    Content-Type: multipart/form-data; boundary=FulltextBoundary
    
    --FulltextBoundary
    
    Content-Disposition: form-data; name="metadata"
    Content-Type: application/json
    
    [Incoming Notification JSON]
    
    --FulltextBoundary
    
    Content-Disposition: form-data; name="content"
    Content-Type: application/zip
    
    [Package]
    
    --FulltextBoundary--
    
  • Aufruf : GET /routed

    1. Liste aller erfolgreich zugestellten Notifikationen
      GET /routed[?<params>]
      
    2. Liste der zugestellten Notifikationen einer Einrichtung
      GET /routed/<repo_id>[?<params>]
      
  • Aufruf : GET /notification

    Eine bestimmte Notification, geliefert im Format “Outgoing Notification JSON” (internes DeepGreen-Format)
    GET /notification/<notification_id>
    

Daneben gibt es, wie eingangs schon erwähnt, einen weiteren Aufruf ausschließlich für Repositorienbetreiber gedacht:

  • Aufruf: POST /config

    Eine neue “match-config“-Datei für das eigene Konto installieren (JSON-Format)
    POST /config?api_key=<api_key>
    Content-Type: application/json; charset=utf-8
    
    [New (overwriting!) match config settings JSON]
    
  • Aufruf: GET /config

    Die aktuellen “match-config“-Setzungen des eigenen Kontos abfragen (JSON-Format)
    GET /config?api_key=<api_key>
    

All diese Aufrufmöglichkeiten der Web-API sollen nun im Folgenden näher erläutert werden.

Artikeldaten an DeepGreen liefern

Vor der Übertragung eines Datenpakets einer Publikation zu DeepGreen kann das Paket von der Datendrehscheibe überprüft werden. Es sind also zwei REST-Resourcen des Web-APIs verfügbar,

  1. Validierung eines Datenpakets (validation),
  2. Übertragung eines Datenpakets (notification).

Für ganz ungeduldige Leser hier zwei (funktionierende!) bash-Beispielskripte, die zip-Pakete mit einem api_key an DeepGreen liefert bzw. validiert. Die Skripte analysieren zunächst jeweils die angegeben zip-Datei, welches Metadatenschema im Datenpaket vorliegt. Momentan werden von DeepGreen drei Schemata verarbeitet, DTD JATS, DTD Journal (dies ist eine Variante des DTD JATS-Schema) und DTD RSC.

bash-Skript zur Validierung
#! /usr/bin/env bash

host_url="https://www.oa-deepgreen.de"

if [ $# -ge 2 ]; then
  api_key=$1
  zip_file=$2
else
  echo "usage: `basename $0` {api-key} {zip-file}"
  exit -1
fi

curl=`which curl`
zipgrep=`which zipgrep`
wc=`which wc`

pkg_fmt="https://datahub.deepgreen.org/FilesAndJATS"
has_xml=`${zipgrep} "DOCTYPE article" ${zip_file} | ${wc} -l`

if [ ${has_xml} -eq 1 ]; then
  is_jrnl=`${zipgrep} "//NLM//DTD Journal " ${zip_file} | ${wc} -l`
  is_jats=`${zipgrep} "//NLM//DTD JATS " ${zip_file} | ${wc} -l`
  is_rsc=`${zipgrep} "//RSC//DTD RSC " ${zip_file} | ${wc} -l`
  if [ ${is_jrnl} -eq 1 ]; then
    pkg_fmt="https://datahub.deepgreen.org/FilesAndJATS"
  elif [ ${is_jats} -eq 1 ]; then
    pkg_fmt="https://datahub.deepgreen.org/FilesAndJATS"
  elif [ ${is_rsc} -eq 1 ]; then
    pkg_fmt="https://datahub.deepgreen.org/FilesAndRSC"
  else
    echo "error: no valid .xml (JATS or RSC) in zip archive found: stop."
    exit -2
  fi
else
  echo "error: no valid (or too many?!) .xml (JATS xor RSC) in zip archive found: stop."
  exit -3
fi

echo "`basename $0`: packaging format in zip archive found:"
echo "`basename $0`: ${pkg_fmt}"

${curl} -i -k -s -XPOST "${host_url}/api/v1/validate?api_key=${api_key}" -F "content=@${zip_file};type=application/zip" -F "metadata=@-;type=application/json" <<EOF
{
  "content" : {
     "packaging_format" : "${pkg_fmt}"
  }
}
EOF

echo
bash-Skript zur Datenpaketübertragung
#! /usr/bin/env bash

host_url="https://www.oa-deepgreen.de"

if [ $# -ge 2 ]; then
  api_key=$1
  zip_file=$2
else
  echo "usage: `basename $0` {api-key} {zip-file}"
  exit -1
fi

curl=`which curl`
zipgrep=`which zipgrep`
wc=`which wc`

pkg_fmt="https://datahub.deepgreen.org/FilesAndJATS"
has_xml=`${zipgrep} "DOCTYPE article" ${zip_file} | ${wc} -l`

if [ ${has_xml} -eq 1 ]; then
  is_jrnl=`${zipgrep} "//NLM//DTD Journal " ${zip_file} | ${wc} -l`
  is_jats=`${zipgrep} "//NLM//DTD JATS " ${zip_file} | ${wc} -l`
  is_rsc=`${zipgrep} "//RSC//DTD RSC " ${zip_file} | ${wc} -l`
  if [ ${is_jrnl} -eq 1 ]; then
    pkg_fmt="https://datahub.deepgreen.org/FilesAndJATS"
  elif [ ${is_jats} -eq 1 ]; then
    pkg_fmt="https://datahub.deepgreen.org/FilesAndJATS"
  elif [ ${is_rsc} -eq 1 ]; then
    pkg_fmt="https://datahub.deepgreen.org/FilesAndRSC"
  else
    echo "error: no valid .xml (JATS or RSC) in zip archive found: stop."
    exit -2
  fi
else
  echo "error: no valid (or too many?!) .xml (JATS xor RSC) in zip archive found: stop."
  exit -3
fi

echo "`basename $0`: packaging format in zip archive found:"
echo "`basename $0`: ${pkg_fmt}"

${curl} -i -k -s -XPOST "${host_url}/api/v1/notification?api_key=${api_key}" -F "content=@${zip_file};type=application/zip" -F "metadata=@-;type=application/json" <<EOF
{
    "content" : {
        "packaging_format" : "${pkg_fmt}"
    }
}
EOF

echo

Es können somit unterschiedliche Rückgabeantworten von DeepGreen erscheinen, je nachdem, ob eine Verifikation oder eine tatsächliche Datenablieferung vorgenommen wird. Der Einfachheit halber werden hier die beiden Funktionen auch nur mit den für sie typischen Anwendungsfälle dokumentiert. Selbstverständlich ist es auch möglich, ein komplettes Datenpaket mit Metadaten samt Volltext(e) validieren zu lassen, ebenso nur Metadaten abzuliefern. Zu beachten bleibt dabei, dass jeweils immer nur ein Artikel (!) pro Datenpaket verwendet wird. Nun die Erklärung der Rückgabewerte im Einzelnen:

Rückgabewerte bei validation (hier am Beispiel: Nur Metadaten abliefern)

Für die Verifikation einer Datenlieferung macht es durchaus Sinn, nur die Metadaten der Lieferung zu schicken. Dazu wird das json-Format “Incoming Notification JSON” zur Beschreibung der zu überprüfenden Metadaten verwendet. Mit Binärdaten gebündelte Lieferungen können natürlich ebenso geprüft werden. Dies funktioniert genau wie im Beispiel notification unten angegeben.

Angabe von Metadaten durch “Incoming Notification JSON” (internes DeepGreen-Format)
POST /validate?api_key=<api_key>
Content-Type: application/json

[Incoming Notification JSON]
  • http-Header Rückgabewerte

    Code Beschreibung

    204 No Content

    Datenpaket ok!

    400 Bad Request

    HTTP 1.1  400 Bad Request
    Content-Type: application/json
    
    {
      "error" : "<verständliche(!) Fehlermeldung (auf englisch)>"
    }
    

    401 Unauthorised

    z.B. ungültiger api_key, falsche Benutzertyp

Soweit die Dokumentation der http-Rückgabewerte der Funktion validation. Nun folgt die Beschreibung der Rückgabewerte bei der Verwendung der Funktion notification.

Rückgabewerte bei notification (am Beispiel: Metadaten samt Volltext(e) abliefern)

Artikellieferungen, die binären Inhalt enthalten sollen (z.B. der Volltext als pdf), werden durch die Kennzeichnung “multipart/form-data” im http-Header gebündelt. Dabei muss im json des Metadatenteil (“Incoming Notifikation JSON”) das Feld content.packaging_format zwingend vorhanden sein.

http-POST: Bündelung durch “Content-Type: multipart/form-data; ...
POST /notification?api_key=<api_key>
Content-Type: multipart/form-data; boundary=FulltextBoundary

--FulltextBoundary

Content-Disposition: form-data; name="metadata"
Content-Type: application/json

[Incoming Notification JSON]

--FulltextBoundary

Content-Disposition: form-data; name="content"
Content-Type: application/zip

[Package]

--FulltextBoundary--
Minimale Angabe der Metadaten durch “packaging_format
POST /notification?api_key=<api_key>
Content-Type: multipart/form-data; boundary=FulltextBoundary

--FulltextBoundary

Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
    "content" : {
        "packaging_format" : "https://datahub.deepgreen.org/FilesAndJATS"
    }
}

--FulltextBoundary

Content-Disposition: form-data; name="content"
Content-Type: application/zip

[Package]

--FulltextBoundary--
  • http-Header Rückgabewerte

    Code Beschreibung

    202 Accepted

    HTTP 1.1  202 Accepted
    Content-Type: application/json
    Location: <URL des api-Endpunkts der akzeptierten Lieferung>
    
    {
      "status" : "accepted",
      "id" : "<eindeutige ID dieser neuen Notifikation>",
      "location" : "<URL des api-Endpunkts dieser Notifikation>"
    }
    

    400 Bad Request

    HTTP 1.1  400 Bad Request
    Content-Type: application/json
    
    {
      "error" : "<verständliche(!) Fehlermeldung (auf englisch)>"
    }
    

    401 Unauthorised

    z.B. ungültiger api_key, falscher Benutzertyp

Artikeldaten von DeepGreen erhalten

Naturgemäß gibt es mehrere Optionen, die Datensammlungen von DeepGreen abzufragen und zu listen. Diese verschiedenen Möglichkeiten werden durch unterschiedliche Aufrufe, aber auch durch bestimmte Parameter festgelegt und gesteuert. Als Parameter für die http-Adressen sind vorgesehen:

Mögliche Parameter bei GET-Funktionen von DeepGreen
GET <http-Adresse/...>?since=<YYYY-MM-DD>
#
# Angabe erforderlich; bestimmt, von wann ab die Notifikationen gelistet werden
#

GET <http-Adresse/...>?pageSize=<number>
#
# Angabe optional, voreingestellt auf 25, maximal 100; bestimmt, wieviele Datensätze auf einmal ausgegeben werden
#

GET <http-Adresse/...>?page=<number>
#
# Angabe optional, voreingestellt auf 1; bestimmt, welche Seite der Resultate ausgegeben wird
#

GET <http-Adresse/...>?api_key=<api_key>
#
# Angabe optional; mit der Angabe wird die Anfrage authentifiziert (z.B. für den Bezug von Volltexten)
#

Mehrere Parameterangaben hintereinander können mit dem &-Zeichen verbunden werden.

Die Notifikationlisten der zugestellten Artikel, die von DeepGreen innerhalb eines gewissen Zeitfensters (typischerweise drei Monate) bereitgestellt werden, sind JSON-Listen des DeepGreen-spezifischen Schemas “Outgoing Notification”.

Volles JSON-Schema für Outgoing Notification (alphabetisch sortiert nach den Schlüsseln)

{
  "analysis_date": "2016-08-09T14:22:11Z",
  "content": {
    "packaging_format": "string"
  },
  "created_date": "2016-08-09T14:22:11Z",
  "embargo": {
    "duration": 0
  },
  "id": "string",
  "issn_data": "string",
  "links": [
    {
      "format": "string",
      "packaging": "string",
      "type": "string",
      "url": "string"
    }
  ],
  "metadata": {
    "author": [
      {
        "affiliation": "string",
        "firstname": "string",
        "identifier": [
          {
            "id": "string",
            "type": "string"
          }
        ],
        "lastname": "string",
        "name": "string"
      }
    ],
    "date_accepted": "2016-08-09T14:22:11Z",
    "date_submitted": "2016-08-09T14:22:11Z",
    "identifier": [
      {
        "id": "string",
        "type": "string"
      }
    ],
    "license_ref": {
      "title": "string",
      "type": "string",
      "url": "string",
      "version": "string"
    },
    "project": [
      {
        "grant_number": "string",
        "identifier": [
          {
            "id": "string",
            "type": "string"
          }
        ],
        "name": "string"
      }
    ],
    "publication_date": "2016-08-09T14:22:11Z",
    "publisher": "string",
    "source": {
      "identifier": [
        {
          "id": "string",
          "type": "string"
        }
      ],
      "name": "string"
    },
    "subject": [
      "string"
    ],
    "title": "string"
  }
}

Die folgende Tabelle gibt eine prägnante Beschreibung für alle im Schema genannten Felder. Sämtliche Felder sind optional; und es sei der Hinweis gestattet, dass weder das Schema noch die Feldbeschreibungen in der Tabelle unter Umständen vollständig sind. Es können in einer weiteren Version von DeepGreen durchaus weitere Felder hinzutreten oder einzelne Felder gelöscht werden.

  • Feldbeschreibung für ausgehende Benachrichtungen (in alphabetischer Reihenfolge)

    Feldbezeichner Beschreibung
    analysis_date Zeitpunkt der Zustellanalyse
    content.packaging_format Format der zugehörigen Binärpakets (meist .zip)
    created_date Zeitpunkt, wann die Notifikation angelegt wurde
    embargo.duration Sperrzeit (Embargo; angegeben in Monaten)
    id Persistenter System-ID für diese Notifikation
    links.format MIME-Typ der Quelle
    links.packaging Paketformat der Quelle
    links.type Schlagwort für den Typ der Quelle (z.B. package)
    links.url URL für die Quelle (verlags- oder systemseitig)
    metadata.author.affiliation Affiliationsangabe, ermittelt aus den Metadaten
    metadata.author.firstname Vorname eines Autors/Urhebers
    metadata.author.lastname Nachname eines Autors/Urhebers
    metadata.author.name Zusammengesetzter Name eines Autors/Urhebers
    metadata.date_accepted Datum, wann die Publikation akzeptiert wurde
    metadata.date_submitted Datum, wann die Publikation eingereicht wurde
    metadata.identifier.id ID für die Publikation (z.B. DOI)
    metadata.identifier.type ID-Typ (z.B. “doi”; allerdings kein Vokabular)
    metadata.license_ref.title Name einer Lizenz (Freifeldtext)
    metadata.license_ref.type Lizenz-Typ (Freifeldtext)
    metadata.license_ref.url URL, die zu weiteren Lizenzinformationen führt
    metadata.license_ref.version Version einer Lizenz
    metadata.project.grant_number Förderkürzel, sofern in den Metadaten angeführt
    metadata.project.identifier.id ID einer Förderung (z.B. Ringold)
    metadata.project.identifier.type ID-Typ in Bezug auf die Förder-ID
    metadata.project.name Name eines Förders / einer Förderinstitution
    metadata.publication_date Publikationsdatum
    metadata.publisher Verlagsname bzw. Verlag
    metadata.source.identifier.id ID der Veröffentlichungsquelle (z.B. ISSN)
    metadata.source.identifier.type ID-Typ der Veröffentlichungsquelle
    metadata.source.name Name der Veröffentlichungsquelle (Journaltitel)
    metadata.subject Schlagwort
    metadata.title Titel der Veröffentlichung

Liste aller erfolgreich zugestellten Artikel

Liste aller erfolgreich zugestellten Notifikationen
GET /routed?since=<YYYY-MM-DD>[&<other params>]
  • http-Header Rückgabewerte

    Code Beschreibung

    200 OK

    HTTP 1.1  200 OK
    Content-Type: application/json
    
    {
      "since" : "<Datumsangabe der Form YYYY-MM-DDThh:mm:ssZ>",
      "page" : "<Seitenzahl dieser Trefferausgabe>",
      "pageSize" : "<Anzahl der Trefferausgabe pro Seite>",
      "timestamp" : "<Zeitstempel der Anfrage>",
      "total" : "<Anzahl der Treffer zu dieser Zeit>",
      "notifications" : [
         "<Liste der 'Outgoing Notification'-JSON-Objekte>"
      ]
    }
    

    400 Bad Request

    HTTP 1.1  400 Bad Request
    Content-Type: application/json
    
    {
      "error" : "<verständliche(!) Fehlermeldung (auf englisch)>"
    }
    

Liste der einer Einrichtung zugestellten Artikel

Liste der zugestellten Notifikationen einer Einrichtung
GET /routed/<repo_id>?since=<YYYY-MM-DD>[&<other params>]
  • http-Header Rückgabewerte

    Code Beschreibung

    200 OK

    HTTP 1.1  200 OK
    Content-Type: application/json
    
    {
      "since" : "<Datumsangabe der Form YYYY-MM-DDThh:mm:ssZ>",
      "page" : "<Seitenzahl dieser Trefferausgabe>",
      "pageSize" : "<Anzahl der Trefferausgabe pro Seite>",
      "timestamp" : "<Zeitstempel der Anfrage>",
      "total" : "<Anzahl der Treffer zu dieser Zeit>",
      "notifications" : [
         "<Liste der 'Outgoing Notification'-JSON-Objekte>"
      ]
    }
    

    400 Bad Request

    HTTP 1.1  400 Bad Request
    Content-Type: application/json
    
    {
      "error" : "<verständliche(!) Fehlermeldung (auf englisch)>"
    }
    

Abfrage eines bestimmten Artikels

Jede Notifikation zu einem Artikel, der von DeepGreen erfolgreich zugestellt werden konnte, ist mit einer eindeutigen ID, der sogenannten Notifikations-ID, gekennzeichnet. Diese ID ist in den Ausgabelisten der vorherigen Abfragen zu finden. Mit der folgenden Anfarge erhält man den individuellen JSON Datensatz einer bestimmten Notifikations-ID.

Abfrage einer bestimmten Notifikation, geliefert im Format “Outgoing Notification JSON” (internes DeepGreen-Format)
GET /notification/<notification_id>
  • http-Header Rückgabewerte

    Code Beschreibung

    200 OK

    HTTP 1.1  200 OK
    Content-Type: application/json
    
    [Outgoing Notification JSON]
    

    404 Not Found

    z.B. die notification_id existiert nicht, oder die Notifikation konnte (noch) nicht zugestellt werden und man ist nicht der Verfasser (d.h. Verlag) der Notifikation (authentifiziert via api_key)

Abruf der Binärdaten einer Notifikation

Über ein spezielles links-Feld im Outgoing Notification JSON, wenn es gesetzt ist, kann dann der entsprechende Volltext bezogen werden, sofern man dazu berechtigt ist. Angenommen, die Notifikation enthielte den JSON-Abschnitt

"links" : [
   {
     "type" : "package",
     "format" : "application/zip",
     "url" : "https://www.oa-deepgreen.de/api/v1/notification/123456789/content",
     "packaging" : "https://datahub.deepgreen.org/FilesAndJATS"
   },
   {
     "type" : "package",
     "format" : "application/zip",
     "url" : "https://www.oa-deepgreen.de/api/v1/notification/123456789/content/SimpleZip",
     "packaging" : "http://purl.org/net/sword/package/SimpleZip"
   }
 ]

dann lautete der Abruf des Volltextes wie folgt:

Abfrage der Binärdaten eines Datenpakets, i.d.R. eine .zip-Datei mit dem/den Volltext(en)
GET <links url>?api_key=<api_key>
  • http-Header Rückgabewerte

    Code Beschreibung

    200 OK

    HTTP 1.1  200 OK
    Content-Type: application/zip
    
    [(binäres) Paket]
    

    401 Unauthorised

    z.B. ungültiger api_key, falsche Benutzertyp oder die entsprechende Notifikation wurde (noch) nicht zugestellt

    404 Not Found

    unter der angegebenen URL gibt es keinen Inhalt bzw. die URL ist schlicht nicht existent

Abfrage und Update der match-config-Setzungen bei Repositorien

Zur Abfrage der aktuellen Affiliations- und weiteren Treffer-Einstellungen eines Repositorienkontos benötigt man natürlich einen gültigen api_key:

Abfrage der aktuellen matching-Kriterien
GET /config?api_key=<api_key>
  • http-Header Rückgabewerte

    Code Beschreibung

    200 OK

    HTTP 1.1  200 OK
    Content-Type: application/json
    
    [matching Kriterien JSON]
    

    401 Unauthorised

    z.B. ungültiger api_key

    404 Not Found

    unter der angegebenen URL gibt es keinen Inhalt bzw. die URL ist schlicht nicht existent (z.B. durch GET /config/)

Update der matching-Kriterien eines Repositorienkontos

Um neue Affiliations- und Treffer-Angaben für ein Repositorium in das zugehörige Konto laden zu können, benötigt man (wie gewohnt) einen gültigen api_key:

Überschreiben der matching-Kriterien mit neuen Werten
POST /config?api_key=<api_key>
Content-Type: application/json; charset=utf-8

[Overwriting new match config settings JSON]
  • http-Header Rückgabewerte

    Code Beschreibung

    200 OK

    HTTP 1.1  200 OK
    Content-Length: 0
    

    401 Unauthorised

    z.B. ungültiger api_key

    400 Bad Request

    Im JSON-Format, das hochgeladen wurde, ist ein Syntax-Fehler festgestellt worden (z.B. ein fehlendes Komma in Aufzählungen)

Beispielhafte, korrekte match-config-Datei im internen JSON-Format

{
  "name_variants": [
    "Academia Fridericiana Erlangensis",
    "Academia Friderico Alexandrina Erlangen-Nürnberg",
    "Academia Friderico-Alexandrina",
    "Academia Regia Bavarica Friderico-Alexandrina",
    "Academia Regia Friderico-Alexandrina",
    "Bayerische Friedrich-Alexanders-Universität",
    "F.A.U. Erlangen-Nürnberg",
    "University of Erlangen"
  ],
  "grants": [
    "2491691", "2673762", "6273863"
  ],
  "domains": [
    "fau.de", "uk-erlangen.de", "uni-erlangen.de"
  ],
  "keywords": [
    "research", "bavarian", "erlangen"
  ]
}