OAI-PMH
=======

.. highlight:: bash

Eine weitere Schnittstelle, die insbesondere für *metadata harvesting*-Prozesse geeignet ist,
stellt DeepGreen mit einer ``OAI-PMH``-konformen An-/Abfragemöglichkeit zur Verfügung (siehe
`Open Archives Initiative (dt.) <https://de.wikipedia.org/wiki/Open_Archives_Initiative>`_).  
Diese Art der Metadaten-Abfrage kann über die Web-Adresse ``https://www.oa-deepgreen.de/oaipmh/``
angesprochen werden, z.B. mit dem Kommando `curl <https://curl.haxx.se>`_ in einer Shell 
(``bash``, ``tcsh``, etc.)::
 
  $ curl -s https://www.oa-deepgreen.de/oaipmh/...

Dabei können (*müssen*!) die ``...`` noch ersetzt werden durch die zwei möglichen 
Aufrufvarianten ``all`` oder ``repo`` der DeepGreen-``OAI-PMH``-Schnittstelle. Wie üblich,
seien im Folgenden mit ``GET`` stets die oben angegebene, komplette ``curl``-Zeile gemeint:


* **Aufruf** :  ``GET /all`` 

  .. code-block:: rest
     :caption: Liste **aller** erfolgreich zugestellten Notifikationen

     GET /all[?<params (i.e. oai_verb + params)>]


* **Aufruf**:  ``GET /repo``

  .. code-block:: rest
     :caption: Liste der zugestellten Notifikationen **einer** Einrichtung

     GET /repo/<repo_id>[?<params (i.e. oai_verb + params)>]


Als illustratives Beispiel sei die Identifikation der DeepGreen-``OAI-PMH``-Schnittstelle 
wiedergegeben::

  $ curl -k -s https://www.oa-deepgreen.de/oaipmh/all?verb=Identify | xml_pp
  <?xml version="1.0" encoding="UTF-8"?>
  <OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
    <responseDate>2018-08-17T10:47:33Z</responseDate>
    <request verb="Identify">http://www.oa-deepgreen.de/oaipmh/all</request>
    <Identify>
      <repositoryName>DeepGreen Prototype OAI-PMH Endpoint</repositoryName>
      <baseURL>http://www.oa-deepgreen.de/oaipmh/all</baseURL>
      <protocolVersion>2.0</protocolVersion>
      <adminEmail>***</adminEmail>
      <earliestDatestamp>2018-05-19T08:47:33Z</earliestDatestamp>
      <deletedRecord>transient</deletedRecord>
      <granularity>YYYY-MM-DDThh:mm:ssZ</granularity>
    </Identify>
  </OAI-PMH>

Hierbei ist zu beachten, dass der frühstmögliche Zeitstempel (``earlierstDatestamp``) immer 
in etwa "-3 Monate" vom Aufrufdatum (``responseDate``) beträgt, da DeepGreen Artikeldaten 
stets nur solange aktuell und somit vorrätig hält (*moving wall*-Prinzip).


Metadaten von DeepGreen erhalten
--------------------------------

Es sei hier noch einmal ausdrücklich darauf hingewiesen, dass die ``OAI-PMH``-Schnittstelle 
von DeepGreen **ausschließlich** nur Metadaten anbietet. Die Auslieferung von Volltexten 
über ``OAI-PMH`` ist (und wird auch zukünftig!) **nicht** vorgesehen.

Der übersichlichkeithalber seien nun kurz die gebäuchlichsten OAI-Verben, die von DeepGreen 
unterstützt werden, gelistet:

.. code-block:: rest
   :caption: Mögliche **Parameter** bei OAI-Verben von DeepGreen

   GET <hhtp-Adresse/...>?verb=Identify
   #
   # Dieses OAI-Verb hat keine weiteren Parameter
   #

   GET <http-Adresse/...>?verb=[ListIdentifiers|ListRecords]&from=<YYYY-MM-DD>
   #
   # Angabe optional; bestimmt, von wann ab die Notifikationen gelistet werden
   # 

   GET <http-Adresse/...>?verb=[ListIdentifiers|ListRecords]&until=<YYYY-MM-DD>
   #
   # Angabe optional, gibt ein (maximales) Enddatum an, bis wohin die Notifikationen gelistet werden
   #

   GET <http-Adresse/...>?verb=GetRecord?identifier=<oai_id>
   #
   # Angabe erforderlich; gibt für dieses OAI-Verb den bestimmen Datensatz an, der geholt werden soll
   #


Bei allen OAI-Verben, die einen oder mehrere Datensätze zurückliefern, **muss** zusätzlich
der Parameter ``...&metadataPrefix=oai_dc`` angehängt werden. Sofern es also für ein OAI-Verb 
sinnvoll (oder vorgeschrieben) ist, werden mit dem ``&``-Zeichen mehrere Parameter verbunden.

Der ``http-Header`` Rückgabewert ist bei allen OAI-Anfragen (gemäß der ``OAI-PMH``-Spezifikation)
stets ``200 OK``:

* **http-Header Rückgabewert**

   +----------------------+-------------------------------------------------------------------+
   | Code                 | Beschreibung                                                      |
   +======================+===================================================================+
   | \                    | .. code-block:: rest                                              |
   |                      |                                                                   |
   | **200** OK           |    HTTP 1.1  200 OK                                               |
   |                      |    Content-Type: text/xml; charset=utf-8                          |
   |                      |                                                                   |
   |                      |    [XML response to OAI-PMH request;                              |
   |                      |     either content (e.g. list of records) or error message]       |
   +----------------------+-------------------------------------------------------------------+



Beispiele für die Benutzung der OAI-PMH-Schnittstelle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Exemplarisches Ergebnis eines ``OAI-PMH``-Aufrufs (mit fiktiver Konto-Nummer 1234567890 ;  
die Notifikations-IDs sind ausgesternt)::

  #
  #  ListIdentifiers
  #
  $ curl -k -s "https://www.oa-deepgreen.de/oaipmh/repo/1234567890?verb=ListIdentifiers&metadataPrefix=oai_dc" | xml_pp
  <?xml version="1.0" encoding="UTF-8"?>
  <OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
    <responseDate>2018-08-20T12:03:31Z</responseDate>
    <request metadataPrefix="oai_dc" verb="ListIdentifiers">http://www.oa-deepgreen.de/oaipmh/repo/1234567890</request>
    <ListIdentifiers>
      <header xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/">
        <identifier>oai:www.oa-deepgreen.de/notification:*****</identifier>
        <datestamp>2018-08-03T07:56:26Z</datestamp>
      </header>
      <header xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/">
        <identifier>oai:www.oa-deepgreen.de/notification:*****</identifier>
        <datestamp>2018-07-04T12:41:44Z</datestamp>
      </header>
      <header xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/">
        <identifier>oai:www.oa-deepgreen.de/notification:*****</identifier>
        <datestamp>2018-06-18T13:39:04Z</datestamp>
      </header>
    </ListIdentifiers>
  </OAI-PMH>

Ein weiteres Beispiel mit konkreten Datensätzen. Anhand der Notifikations-IDs (hier ausgesternt) 
könnten die berechtigten Repositorien die Artikel ggf. über die Web-API von DeepGreen beziehen::

  #
  #  ListRecords
  #
  $ curl -k -s "https://www.oa-deepgreen.de/oaipmh/repo/1234567890?verb=ListRecords&metadataPrefix=oai_dc" | xml_pp
  <?xml version="1.0" encoding="UTF-8"?>
  <OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
    <responseDate>2018-08-20T12:24:10Z</responseDate>
    <request metadataPrefix="oai_dc" verb="ListRecords">http://www.oa-deepgreen.de/oaipmh/repo/1234567890</request>
    <ListRecords>
      <record>
        <header xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/">
          <identifier>oai:www.oa-deepgreen.de/notification:*****</identifier>
          <datestamp>2018-08-10T08:29:00Z</datestamp>
        </header>
        <metadata xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/">
          <oai_dc:dc xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
            <dc:title>Healthcare IT Utilization and Penetration among Physicians: Novel IT Solutions in Healthcare – Use and Acceptance in Hospitals</dc:title>
            <dc:publisher>S. Karger AG</dc:publisher>
            <dc:identifier>issn:0014-312X</dc:identifier>
            <dc:identifier>issn:1421-9921</dc:identifier>
            <dc:identifier>doi:10.1159/000490241</dc:identifier>
            <dc:creator>Ferdinand Vogt</dc:creator>
            <dc:creator>Fritz Seidl</dc:creator>
            <dc:creator>Giuseppe Santarpino</dc:creator>
            <dc:creator>Martijn van Griensven</dc:creator>
            <dc:creator>Martin Emmert</dc:creator>
            <dc:creator>Guenther Edenharter</dc:creator>
            <dc:creator>Dominik Pförringer</dc:creator>
            <dc:contributor>eDepartment of Anaesthesiology, Klinikum rechts der Isar, Technical University of Munich, Munich, Germany</dc:contributor>
            <dc:contributor>bDepartment of Trauma Surgery, Klinikum rechts der Isar, Technical University of Munich, Munich, Germany</dc:contributor>
            <dc:contributor>bDepartment of Trauma Surgery, Klinikum rechts der Isar, Technical University of Munich, Munich, Germany; cDepartment of Experimental Trauma Surgery, Klinikum rechts der Isar, Technical University of Munich, Munich, Germany</dc:contributor>
            <dc:contributor>aDepartment of Cardiac Surgery, Klinikum Nürnberg, Paracelsus Medical University, Nuremberg, Germany</dc:contributor>
            <dc:contributor>cDepartment of Experimental Trauma Surgery, Klinikum rechts der Isar, Technical University of Munich, Munich, Germany</dc:contributor>
            <dc:contributor>dInstitute of Management (IFM), School of Business and Economics, Friedrich Alexander University Erlangen-Nuremberg, Nuremberg, Germany</dc:contributor>
            <dc:date>2018-07-26T00:00:00Z</dc:date>
            <dc:rights>Alliance License DFG</dc:rights>
            <dc:subject>Original Paper</dc:subject>
            <dc:subject>Health monitoring</dc:subject>
            <dc:subject>Information technology</dc:subject>
            <dc:subject>Physicians</dc:subject>
            <dc:subject>Demand</dc:subject>
            <dc:subject>Outlook</dc:subject>
            <dc:subject>Expectations</dc:subject>
            <dc:subject>Data storage</dc:subject>
            <dc:subject>Healthcare IT</dc:subject>
          </oai_dc:dc>
        </metadata>
      </record>
      <record>
        <header xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/">
          <identifier>oai:www.oa-deepgreen.de/notification:*****</identifier>
          <datestamp>2018-08-10T08:34:06Z</datestamp>
        </header>
        <metadata xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/">
          <oai_dc:dc xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
            <dc:title>Gastrointestinal Stromal Tumors: Clinical Symptoms, Location, Metastasis Formation, and Associated Malignancies in a Single Center Retrospective Study</dc:title>
            <dc:publisher>S. Karger AG</dc:publisher>
            <dc:identifier>issn:0257-2753</dc:identifier>
            <dc:identifier>issn:1421-9875</dc:identifier>
            <dc:identifier>doi:10.1159/000489556</dc:identifier>
            <dc:creator>Ali Aghdassi</dc:creator>
            <dc:creator>Agnes Christoph</dc:creator>
            <dc:creator>Frank Dombrowski</dc:creator>
            <dc:creator>Paula Döring</dc:creator>
            <dc:creator>Christoph Barth</dc:creator>
            <dc:creator>Jan Christoph</dc:creator>
            <dc:creator>Markus M. Lerch</dc:creator>
            <dc:creator>Peter Simon</dc:creator>
            <dc:contributor>aDepartment of Medicine A, University Medicine Greifswald, Greifswald, Germany</dc:contributor>
            <dc:contributor>dChair of Medical Informatics, Friedrich-Alexander-University Erlangen-Nürnberg, Erlangen, Germany</dc:contributor>
            <dc:contributor>cGastroenterologische Praxis, Kempten, Germany</dc:contributor>
            <dc:contributor>bInstitute of Pathology, University Medicine Greifswald, Greifswald, Germany</dc:contributor>
            <dc:date>2018-06-05T00:00:00Z</dc:date>
            <dc:rights>Alliance License DFG</dc:rights>
            <dc:subject>Stomach and Duodenum: Original Paper</dc:subject>
            <dc:subject>Gastrointestinal stromal tumor</dc:subject>
            <dc:subject>Gastrointestinal oncology</dc:subject>
            <dc:subject>Gastrointestinal symptoms</dc:subject>
            <dc:subject>Gastrointestinal tract</dc:subject>
            <dc:subject>Metastasis</dc:subject>
            <dc:subject>Recurrence</dc:subject>
          </oai_dc:dc>
        </metadata>
      </record>
    </ListRecords>
  </OAI-PMH>