SWORD(v2)

Die Datendrehscheibe bietet auch die Möglichkeit, Artikeldaten über die sogenannte SWORD-Schnittstelle (engl.) zu verarbeiten. Es wird die aktuelle Version v2 angeboten. Mehrfache Tests haben gezeigt, dass v2 abwärtskombatible zu der älteren Fassung v1 ist. Das SWORD-Protokoll wird, genau wie die native Web-API von DeepGreen, über eine Basis-HTTP-Adresse, https://www.oa-deepgreen.de/sword angesprochen, z.B. mit dem Kommando curl in einer Shell (bash, tcsh, etc.):

$ curl -s -u "<dg_username>:<api_key>" [-X GET|POST] https://www.oa-deepgreen.de/sword/...

Dabei werden in den nun nachfolgende Beispielen die ... ersetzt durch die konkreten Endpunkte validate, notify, collection und entry der SWORD-Schnittstelle. Diese Endpunkte sind nur für Verlagskonten freigeschaltet und zugänglich, Repositorienkonten dagegen haben keinerlei Zugriff auf diese!

Zwingend notwendig für einen erfolgreichen Verbindungsaufbau und -abwicklung ist dabei die Angabe eines gültigen DeepGreen-Kontonamens dg_username samt dessen API-Schlüssels api_key. Ohne diese Angaben zur Authentifizierung wird der Verbindungsaufbau abgelehnt, und man erhält keinen Zugang. Im Folgenden soll der Übersichtlichkeit halber GET und POST für die gesamte, mit einer wie oben angegeben gültigen Kennung versehenen curl-Zeile geschrieben werden. Hier ein kleiner Überblick der möglichen Aufrufe in dieser Kurzform:

• Aufruf : GET /service-document

  Abfrage des SWORD-Servicedokuments, einer konkreten Beschreibung aller von DeepGreen angebotenen SWORD-Funktionalitäten

  GET /service-document
  

• Aufruf : POST /collection/validate

  Bemerkung : Hierbei findet kein(!) Doublettencheck statt.

  Überprüfung eines Artikeldatenpakets auf Syntax- oder sonstiger Fehler ( ohne Doublettencheck! )

  POST /collection/validate
  Content-Disposition: filename=article.zip
  Content-Type: application/zip
  Packaging: https://datahub.deepgreen.org/FilesAndJATS
  
  [binäre .zip-Datei]
  

• Aufruf : POST /collection/notify

  Bemerkung : Hierbei findet kein(!) Doublettencheck statt.

  Neue Artikeldaten an DeepGreen senden

  POST /collection/notify
  Content-Disposition: filename=article.zip
  Content-Type: application/zip
  Packaging: https://datahub.deepgreen.org/FilesAndJATS
  
  [binäre .zip-Datei]
  

• Aufruf : GET /entry/<notification_id>

  Details einer (eigenen!) Notifikation abfragen

  GET /entry/<notification_id>
  

• Aufruf : GET /entry/<notification_id>/content

  Den binären Inhalt (i.d.R. den Volltext als .pdf) einer (eigenen!) Notifikation abfragen (zur Überprüfung?!)

  GET /entry/<notification_id>/content
  

• Aufruf : GET /entry/<notification_id>/statement/atom

  Statusabfrage für eine (eigenen!) Notifikation (hier als Atom-Feed)

  GET /entry/<notification_id>/statement/atom
  

Artikeldaten an DeepGreen liefern

Eine Abfrage des Service-Dokuments des in der Datendrehscheibe implementierten SWORD-Servers liefert folgende Antwort:

$ curl -k -s https://[Account-Name]@www.oa-deepgreen.de/sword/service-document
<service xmlns:dcterms="http://purl.org/dc/terms/" xmlns:sword="http://purl.org/net/sword/terms/" xmlns:atom="http://www.w3.org/2005/Atom" xmlns="http://www.w3.org/2007/app">
  <sword:version>2.0</sword:version>
  <sword:maxUploadSize>16777216</sword:maxUploadSize>
  <workspace>
    <atom:title>DeepGreen Prototype</atom:title>
    <collection href="https://www.oa-deepgreen.de/sword/collection/validate">
      <atom:title>Validate</atom:title>
      <accept>*/*</accept>
      <sword:collectionPolicy>This collection will take any deposit package intended for the DeepGreen service</sword:collectionPolicy>
      <dcterms:abstract>Deposit here to validate the format of your notification files</dcterms:abstract>
      <sword:mediation>true</sword:mediation>
      <sword:treatment>Packages sent here will be validated, and you will receive an error document or a deposit receipt.  The deposit will not subsequently be stored, so you will not be able to retrieve it again afterwards.</sword:treatment>
      <sword:acceptPackaging>https://datahub.deepgreen.org/FilesAndJATS</sword:acceptPackaging>
      <sword:acceptPackaging>https://datahub.deepgreen.org/FilesAndRSC</sword:acceptPackaging>
    </collection>
    <collection href="https://www.oa-deepgreen.de/sword/collection/notify">
      <atom:title>Notify</atom:title>
      <accept>*/*</accept>
      <sword:collectionPolicy>This collection will take any deposit package intended for the DeepGreen service</sword:collectionPolicy>
      <dcterms:abstract>Deposit here to deliver a publication event notification</dcterms:abstract>
      <sword:mediation>true</sword:mediation>
      <sword:treatment>Packages sent here will be analysed for metadata suitable for routing to appropriate repository systems, and then delivered onward.</sword:treatment>
      <sword:acceptPackaging>https://datahub.deepgreen.org/FilesAndJATS</sword:acceptPackaging>
      <sword:acceptPackaging>https://datahub.deepgreen.org/FilesAndRSC</sword:acceptPackaging>
    </collection>
  </workspace>
</service>

Demzufolge gibt es zwei Einstiegspunkte, um über die SWORD-Schnittstelle Artikeldaten an die Datendrehscheibe zu schicken, einmal über den Endpunkt .../collection/validate und einmal über den Endpunkt .../collection/notify. Der Unterschied in diesen beiden Empfangsadressen besteht darin, dass nur bei der Benutzung der zweiten Adresse die gesendeten Daten tatsächlich in die Drehscheibe aufgenommen, analysiert und ggf. Benachrichtigungen ausgelöst werden, falls es zulässige Abnehmer, sprich legitime Repositorien für Open Access-Zweitveröffentlichungen gibt.

Rückgabewerte bei .../collection/validate

Für die Verifikation einer zip-Datei, ob sie als Datenlieferung geeignet ist, kann die folgende Kommando-Zeile verwendet werden:

$ curl -k -s -i -u "<dg_username>:<api_key>" -X POST https://www.oa-deepgreen.de/sword/collection/validate -H "Packaging: https://datahub.deepgreen.org/FilesAndJATS" -H "Content-Type: application/zip" --data-binary "@test.zip"

Hierbei ist unter @test.zip die zu überprüfende zip-Datei angegeben. Die header-Angabe Packaging: https://datahub.deepgreen.org/FilesAndJATS ist unbedingt erforderlich, da sonst die zip-Datei nicht von der Datendrehscheibe analysiert werden kann.

Der generelle header-Aufbau ist in der folgenden, formalen Syntaxbeschreibung, zusammen mit den möglichen Rückgabewerten der http-Anfrage, ersichtlich.

POST /collection/validate
Content-Disposition: filenname=test.zip
Content-Type: application/zip
Packaging: https://datahub.deepgreen.org/FilesAndJATS

[Binäre .zip-Datei]

• http-Header Rückgabewerte

  Code	Beschreibung
  202 Accepted	Datenpaket ok!
  401 Unauthorised	z.B. ungültiger api_key, falsche Benutzertyp
  404 Not Found	HTTP/1.1 404 Not Found Server: nginx/1.12.2 Content-Type: text/xml; charset=utf-8 Content-Length: 0
  500 Internal Server Error	z.B. ungültige Datei oder Header-Angabe (Packaging)

Als nächstes kommt nun eine Beschreibung des völlig analogen Falls der Datenablieferung, bei dem ein intaktes Artikeldatenpaket tatsächlich an DeepGreen zur weiteren Verarbeitung übertragen wird.

Rückgabewerte bei .../collection/notify

Für die reale Datenablieferung einer zip-Datei, kann (ensprechend der gerade beschriebenen Verifikation) die folgende Kommando-Zeile verwendet werden:

$ curl -k -s -i -u "<dg_username>:<api_key>" -X POST https://www.oa-deepgreen.de/sword/collection/notify -H "Packaging: https://datahub.deepgreen.org/FilesAndJATS" -H "Content-Type: application/zip" --data-binary "@article.zip"

Hierbei ist unter @article.zip die an DeepGreen zu übertragene zip-Datei angegeben. Die header-Angabe Packaging: https://datahub.deepgreen.org/FilesAndJATS ist unbedingt erforderlich, da sonst die zip-Datei nicht von der Datendrehscheibe analysiert und angenommen werden kann.

Der generelle header-Aufbau ist in der folgenden, formalen Syntaxbeschreibung, zusammen mit den möglichen Rückgabewerten der http-Anfrage, ersichtlich.

POST /collection/notify
Content-Disposition: filenname=article.zip
Content-Type: application/zip
Packaging: https://datahub.deepgreen.org/FilesAndJATS

[Binäre .zip-Datei]

• http-Header Rückgabewerte

  Code	Beschreibung
  201 Created	Datenpaket zur weiteren Verarbeitung angenommen!
  401 Unauthorised	z.B. ungültiger api_key, falsche Benutzertyp
  404 Not Found	HTTP/1.1 404 Not Found Server: nginx/1.12.2 Content-Type: text/xml; charset=utf-8 Content-Length: 0
  500 Internal Server Error	z.B. ungültige Datei oder Header-Angabe (Packaging)

Im Erfolgsfall [201 Created] wird zusätzlich noch eine SWORD-Empfangsbestätigung in Form einer ATOM-Meldung zurückgeliefert (siehe für die Einzelheiten auch die Spezifikation der SWORD-Schnittstelle (engl.) ):

$ curl -k -s -u "<dg_username:<api_key>" -H "Packaging: https://datahub.deepgreen.org/FilesAndJATS" -H "Content-Type: application/zip" https://www.oa-deepgreen.de/sword/collection/notify --data-binary "@article.zip"
<entry xmlns:dcterms="http://purl.org/dc/terms/" xmlns:sword="http://purl.org/net/sword/terms/" xmlns="http://www.w3.org/2005/Atom">
  <title>DeepGreen Notification</title>
  <id>tag:container@deepgreen/b776b7ec1bec4ac18c4dfdc277696f51</id>
  <updated>2017-11-07T17:05:37Z</updated>
  <author>
    <name>DeepGreen Prototyp</name>
  </author>
  <summary type="text"></summary>
  <generator uri="https://www.oa-deepgreen.de" version="2.0"/>
  <dcterms:creator>DeepGreen Prototyp</dcterms:creator>
  <dcterms:title>DeepGreen Notification</dcterms:title>
  <sword:treatment>Notification has been accepted for routing</sword:treatment>
  <content type="application/zip" src="https://www.oa-deepgreen.de/sword/entry/b776b7ec1bec4ac18c4dfdc277696f51/content"/>
  <link rel="edit" href="https://www.oa-deepgreen.de/sword/entry/b776b7ec1bec4ac18c4dfdc277696f51"/>
  <link rel="edit-media" type="application/zip" href="https://www.oa-deepgreen.de/sword/entry/b776b7ec1bec4ac18c4dfdc277696f51/content"/>
  <sword:packaging>https://datahub.deepgreen.org/FilesAndJATS</sword:packaging>
  <link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed" href="https://www.oa-deepgreen.de/sword/entry/b776b7ec1bec4ac18c4dfdc277696f51/statement/atom"/>
  <link rel="http://purl.org/net/sword/terms/statement" type="application/rdf+xml" href="https://www.oa-deepgreen.de/sword/entry/b776b7ec1bec4ac18c4dfdc277696f51/statement/rdf"/>
  <link rel="http://purl.org/net/sword/terms/originalDeposit" href="https://www.oa-deepgreen.de/sword/entry/b776b7ec1bec4ac18c4dfdc277696f51/content"/>
</entry>

Nach der erfolgreichen Datenlieferung gibt es darüberhinus noch Abfragemöglichkeiten zu den gesendeten Datenpaketen. Dies geschieht durch die in der Empfangsquittung unter <link rel="edit"...> angegebene http-Adresse: https://www.oa-deepgreen.de/sword/entry/<id> .

Weitere Überprüfung von gesendeten Artikeldaten

Mit der <id> aus dem edit-Feld der Empfangsbestätigung kann der Sender des Datenpakets (und sonst niemand!)

1. eine Kopie der Empfangsbestätigung erhalten:

   $ curl -k -s -i -u "dg_username>:<api_key>" https://www.oa-deepgreen.de/sword/entry/b776b7ec1bec4ac18c4dfdc277696f51
   

2. eine Kopie des geschickten Binärdatenpakets (ZIP-Datei) erhalten:

   $ curl -k -s -i -u "dg_username>:<api_key>" https://www.oa-deepgreen.de/sword/entry/b776b7ec1bec4ac18c4dfdc277696f51/content
   

3. eine Statusmeldung über den Bearbeitungsstand nachfragen, ob das Paket zugestellt wurde oder nicht:

   $ curl -k -s -i -u "dg_username>:<api_key>" https://www.oa-deepgreen.de/sword/entry/b776b7ec1bec4ac18c4dfdc277696f51/statement/atom
   

   Bei dieser Abfrage des Bearbeitungszustands kann optional mit der Angabe von zusätzlichen Headern in der Kommandozeile das Rückgabeformat bestimmt werden,

   -H "Accept: application/atom+xml;type=feed" bzw. -H "Accept: application/rdf+xml".

Artikeldaten von DeepGreen erhalten

In DeepGreen besteht auch die Möglichkeit, dass über eine SWORD-Schnittstelle die Benachrichtigungen und Volltexte automatisiert in dafür vorgesehene collections der empfangenden Repositorien gespielt werden.

Die dafür nötigen Einstellungen in den Repositorien hängen sehr stark von den Zielsystemen ab, und bedürfen u.U. sehr sorgfältige Vorbereitungen. Diese können hier – aus rein praktikablen Gründen – nicht in aller Ausführlichkeit beschrieben werden, zumal diese Beschreibungen nach einem Versionswechsel des Repositorium mit einiger Sicherheit schnell veraltet wären. Daher ist es ratsamer, das aktuelle Repositorien-Handbuch zu konsultieren oder die jeweilige lokale IT-Administration mit diesen Fragen zu behelligen.

Rudimentär unterstützt DeepGreen die Repositorien EPrints, OPUS4, ESciDoc und DSpace (in zwei Varianten: METSDSpaceSIP und METSMODS).