Diese Seite dienst als Beschreibung der öffentlichen OAI-Schnittstelle der DDB. Diese Dokumentation soll zum einen als Vorgabe für die Implementierung der Schnittstelle verwendet werden, aber auch später in einer überarbeiteten und konsolidierten Fassung veröffentlicht werden.

Inhalt

Allgemeines

Eine OAI-Schnittstelle bietet die folgenden „Verben“, mit denen Daten abgefragt werden können. Die OAI-PMH 2.0-Spezifikation befindet sich unter http://www.openarchives.org/OAI/openarchivesprotocol.html, weitere einführende Informationen gibt es bei Wikipedia unter https://en.wikipedia.org/wiki/Open_Archives_Initiative_Protocol_for_Metadata_Harvesting.

GetRecord: Abfragen eines Datensatzes
Identify: Abfragen grundsätzlicher Informationen über den Provider, hier die DDB
ListIdentifiers: Abfragen mehrerer Datensatzinformationen (wie beispielsweise die Identifier)
ListMetadataFormats: Abfrage verfügbarer Metadatenformate, hier oai_dc und edm
ListRecords: Abgraben mehrerer Datensätze
ListSets: Abfragen vorhandener Sets

Datenweitergabe an Europeana

Workflow

DDB-Dokumentation > OAI/PMH-Schnittstelle > oai.png

Vorverarbeitung durch Transformation

Beim Erstellen der Daten für die Weitergabe an Europeana (Datenformat EDM) werden bereits die folgenden Punkt erledigt und müssen folglich durch den OAI/PMH-Server nicht berücksichtig werden.

bei Objekten mit keiner CC0-Lizenz werden nur Kernmetadaten exportiert (dc:description wird gelöscht)
bestimmte Hierarchieobjekte (z. B. Kapitel) werden herausgefiltert
Text-Objekte ohne Sprache werden rausgefiltert
Objekte ohne Digitalisat werden rausgefiltert
Objekte ohne edm:type werden rausgefiltert

Spezifikation

Datenformate

Über die OAI-Schnittstelle der DDB werden die folgenden beiden Datenformate angeboten:

DDB (Primary Format, needed to define set-definitions. as set-definitions are defined by xPath-Expressions)
OAI-DC
EDM

Identifier

Die OAI-Schnittstelle der DDB benutzt die nach außen öffentlich sichtbaren Identifier. Das sind (Teile des) URI der DDB-Objekte.

DDB-Objekt (Peterchens Mondfahrt): http://www.deutsche-digitale-bibliothek.de/item/IDEYVAM52SZTJUSL347PX6JUIFR545ZD

Datenzusammenstellungen, darunter fallen u.a. OAI-Datensets bekommen zukünftig einen eigenen Identifier.

Sammlung: http://www.deutsche-digitale-bibliothek.de/dataset/ABCDEFGHIJKLMNOPQRSTU0123456789

Einstweilen werden OAI-Datensetz wie u.g eindeutig identifiziert.

OAI-Datensets:

Generelle Datensets

Lieferung an Europeana

Kriterium	Benennung der Datensets	Kommentar	Beispiele
dataset_id	<dataset_id>	ID des Datensets. (dies wird am häufigsten benutzt)	dataset-id:5738807392711401XjYt
dataset_id AND provider_id	<dataset_id>_<provider_id>	Ein Datenpartner kann mehrere Provider liefern. Nur einige müssen an Europeana weitergegeben werden (z.B. Digicult)	dataset-id:5738807392711401XjYt AND provider_id:VSHJWG7QLS7Y3NS2HKE43E5Q5NJ7OCLS
dataset_id AND type_fct	<dataset_id>_<type_fct>	Ein Datenpartner möchte z.B. nur die Videos aus einem Datenset liefern.	dataset-id:5738807392711401XjYt AND type_fct:mediatype_005
dataset_id AND license	<dataset_id>_<license>	Ein Datenpartner möchte nur die Objekte mit der Lizenz “RV-FZ” innerhalb eines Datensets liefern	dataset-id:5738807392711401XjYt AND license:"http://www.deutsche-digitale-bibliothek.de/lizenzen/rv-fz/"

Blacklisting:

TODO Büchner, Michael

Weitere Anforderungen

Das Harvesting einzelner DDB-IDs sollte möglich sein (GetRecord).
Veränderungen innerhalb einen OAI-Datensets müssen über die Zeit durch einen Timestamp abfragbar sein.

Fragen & Antworten

Zusammenhang: Europeana-Weitergabe und Blacklisting

Stand der Dinge: Das ist ein vertragliches Problem und muss auch an dieser Stelle gelöst werden. Ein Blacklisting (Daten eines Datenpartners lassen sich nicht über die DDB-API abrufen) sollte nicht mit einer Datenlieferung über die DDB an Europeana kombiniert werden können.
Für alle nicht-geblacklisteten Daten werden OAI-Sets erstellt.

Ist eine Freischaltung auf dem OAI Server noch nötig? (Whitelist)

Nein, eine zusätzliche Freischaltung ist nicht vorgesehen. Jedes DDB-Objekt bekommt auf dem OAI-Server einen OAI/DC-Datensatz, der erst einmal nur die DDB-ID enthält. J).

Daten in den Lieferformate harvesten (Anforderung FS Archiv für EAD)

Anforderung ist erst einmal zurückgestellt.

Umgang mit Deleted Records

Deleted Records werden gemäß der OAI/PMH-Spezifikation unterstützt.

Löschen von OAI-Sets

Komplette Neuindexierung notwendig. Das ist bisher nicht implementiert

Konventionen/Festlegungen

Alle Datumswerte werden als UTC-Zeit (ohne Zeitzone) verwendet.
Das Format ist „yyyy-mm-ddTHH:mm:ssZ“, z. B. 2016-07-01T09:27:00Z}}
Die OAI-Schnittstelle der DDB ist unter https://oai.deutsche-digitale-bibliothek.de/ erreichbar. http://oai.deutsche-digitale-bibliothek.de/ leitet auf die verschlüsselte Schnittstelle weiter.
…

Schemata/XSLT-Stylesheet

Zur besseren Verwendbarkeit der Schnittstelle ist das OAI PMH 2.0-Schema eingebunden.

<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" 
  xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">

Weiterhin ist mittels einer Prozessoranweisung ein XSLT-Stylesheet eingebunden. Das ermöglicht den meisten Webbrowsern aus den XML-Daten der OAI-Schnittstelle eine HTML-Ansicht zu generieren.

<?xml-stylesheet type='text/xsl' 
  href='https://oai.deutsche-digitale-bibliothek.de/oai2.xsl'?>

Das entsprechende XSLT-Stylesheet kann bspw. unter http://wiki.eprints.org/w/OAI_XSLT heruntergeladen werden und muss durch die OAI-Schnittstelle ausgeliefert werden. Ggf. kann die Datei noch angepasst werden, damit die Anzeige im Corporate-Design der DDB erfolgt.

Beschreibung

GetRecord

URL	https://oai.deutsche-digitale-bibliothek.de?verb=GetRecord
Parameter	identifier (benötigt)
	metadataPrefix (benötigt)	Metadatenformat: „oai_dc” oder „edm“

Request

https://oai.deutsche-digitale-bibliothek.de?verb=GetRecord&metadataPrefix=edm&identifier=https%3A%2F%2Fwww.deutsche-digitale-bibliothek.de%2Fitem%2FIDEYVAM52SZTJUSL347PX6JUIFR545ZD

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?xml-stylesheet type='text/xsl' href='https://oai.deutsche-digitale-bibliothek.de/oai2.xsl'?>
<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>2017-01-17T13:33:19.399Z</responseDate>
  <request 
    identifier="https://www.deutsche-digitale-bibliothek.de/item/IDEYVAM52SZTJUSL347PX6JUIFR545ZD" 
    metadataPrefix="edm" 
    verb="GetRecord">https://oai.deutsche-digitale-bibliothek.de/</request>
  <GetRecord>
    <record>
      <header>
        <identifier>https://www.deutsche-digitale-bibliothek.de/item/IDEYVAM52SZTJUSL347PX6JUIFR545ZD</identifier>
        <!-- Datum vom ingestDate -->
        <datestamp>2015-06-15T01:11:30Z</datestamp>
        <!-- Auflistung ALLER Sets in denen der Datensatz vorkommt -->
        <setSpec>5738807392711401XjYt</setSpec>
        <setSpec>5738807392711401XjYt_VSHJWG7QLS7Y3NS2HKE43E5Q5NJ7OCLS</setSpec>
        <setSpec>5738807392711401XjYt_mediatype_005</setSpec>
      </header>
      <metadata>
        <!-- Nicht valide. Bessere Vorschläge sind willkommen! Europeana macht es auch so. -->
        <rdf:RDF 
          xmlns:edm="http://www.europeana.eu/schemas/edm/" 
          xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
          <!-- ... -->
        </rdf:RDF>
      </metadata>
    </record>
  </GetRecord>
</OAI-PMH>

Identify

URL	https://oai.deutsche-digitale-bibliothek.de?verb=Identify
Parameter	-

Request

https://oai.deutsche-digitale-bibliothek.de?verb=Identify

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?xml-stylesheet type='text/xsl' href='https://oai.deutsche-digitale-bibliothek.de/oai2.xsl'?>
<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>2017-01-12T13:12:34Z</responseDate>
  <request verb="Identify">https://oai.deutsche-digitale-bibliothek.de/</request>
  <Identify>
    <repositoryName>Deutsche Digitale Bibliothek</repositoryName>
    <baseURL>https://oai.deutsche-digitale-bibliothek.de/</baseURL>
    <protocolVersion>2.0</protocolVersion>
    <adminEmail>service@deutsche-digitale-bibliothek.de</adminEmail>
    <earliestDatestamp>1998-05-13T00:00:00Z</earliestDatestamp>
    <deletedRecord>yes</deletedRecord>
    <granularity>YYYY-MM-DDThh:mm:ssZ</granularity>
  </Identify>
</OAI-PMH>

ListIdentifiers

URL	https://oai.deutsche-digitale-bibliothek.de?verb=ListIdentifiers&metadataPrefix=oai_dc
Parameter	metadataPrefix (benötigt)	Metadatenformat: „oai_dc” oder „edm“
	from (optional)	UTC-Zeit in der Form „yyyy-mm-ddTHH:mm:ssZ“
	until (optional)	UTC-Zeit in der Form „yyyy-mm-ddTHH:mm:ssZ“
	set (optional)	OAI-Set-Identifier
	resumptionToken (optional)	Token zur Wiederaufnahme bei größeren Datensets

Request

https://oai.deutsche-digitale-bibliothek.de?verb=ListIdentifiers&metadataPrefix=oai_dc

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type='text/xsl' href='https://oai.deutsche-digitale-bibliothek.de/oai2.xsl'?>
<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>2017-01-13T08:45:20.794Z</responseDate>
   <request metadataPrefix="oai_dc" verb="ListIdentifiers">https://oai.deutsche-digitale-bibliothek.de/</request>
   <ListIdentifiers>
      <header>
         <identifier>https://www.deutsche-digitale-bibliothek.de/item/IDEYVAM52SZTJUSL347PX6JUIFR545ZD</identifier>
         <!-- Datum vom ingestDate -->
         <datestamp>2015-06-15T01:11:30Z</datestamp>
         <!-- Auflistung ALLER Sets in denen der Datensatz vorkommt -->
         <setSpec>5738807392711401XjYt</setSpec>
         <setSpec>5738807392711401XjYt_VSHJWG7QLS7Y3NS2HKE43E5Q5NJ7OCLS</setSpec>
         <setSpec>5738807392711401XjYt_mediatype_005</setSpec>
      </header>
      <header>
         <identifier>K6UAEV22DSH4GC2VAKPRTF4ZOHIOU6EJ</identifier>
         <datestamp>2015-06-15T01:11:32Z</datestamp>
         <setSpec>5738807392711401XjYt</setSpec>
         <setSpec>5738807392711401XjYt_VSHJWG7QLS7Y3NS2HKE43E5Q5NJ7OCLS</setSpec>
         <setSpec>5738807392711401XjYt_mediatype_005</setSpec>
      </header>
      <!-- ... -->
      <resumptionToken completeListSize="6200747" cursor="0" expirationDate="2017-01-13T09:15:20Z">mCgPm-947-0</resumptionToken>
   </ListIdentifiers>
</OAI-PMH>

ListMetadataFormats

URL	https://oai.deutsche-digitale-bibliothek.de?verb=ListMetadataFormats
Parameter	identifier (optional)	Identifier eines DDB-Objektes (URI)

Request

https://oai.deutsche-digitale-bibliothek.de?verb=ListMetadataFormats

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?xml-stylesheet type='text/xsl' href='https://oai.deutsche-digitale-bibliothek.de/oai2.xsl'?>
<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>2017-01-12T13:36:57Z</responseDate>
  <request verb="ListMetadataFormats">https://oai.deutsche-digitale-bibliothek.de/</request>
  <ListMetadataFormats>
    <metadataFormat>
      <metadataPrefix>oai_dc</metadataPrefix>
      <schema>http://www.openarchives.org/OAI/2.0/oai_dc.xsd</schema>
      <metadataNamespace>http://purl.org/dc/elements/1.1/</metadataNamespace>
    </metadataFormat>
    <metadataFormat>
      <metadataPrefix>edm</metadataPrefix>
      <schema>http://www.europeana.eu/schemas/edm/EDM.xsd</schema>
      <metadataNamespace>http://www.europeana.eu/schemas/edm/</metadataNamespace>
    </metadataFormat>
  </ListMetadataFormats>
</OAI-PMH>

ListRecords

URL	https://oai.deutsche-digitale-bibliothek.de?verb=ListRecords
Parameter	metadataPrefix (benötigt)	Metadatenformat: „oai_dc” oder „edm“
	from (optional)	UTC-Zeit in der Form „yyyy-mm-ddTHH:mm:ssZ“
	until (optional)	UTC-Zeit in der Form „yyyy-mm-ddTHH:mm:ssZ“
	set (optional)	OAI-Set-Identifier
	resumptionToken (optional)	Token zur Wiederaufnahme bei größeren Datensets

Request

https://oai.deutsche-digitale-bibliothek.de/?verb=ListRecords&metadataPrefix=edm

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?xml-stylesheet type='text/xsl' href='https://oai.deutsche-digitale-bibliothek.de/oai2.xsl'?>
<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>2017-01-17T15:50:20Z</responseDate>
  <request metadataPrefix="edm" verb="ListRecords">https://oai.deutsche-digitale-bibliothek.de/</request>
  <ListRecords>
    <record>
      <header>
        <identifier>https://www.deutsche-digitale-bibliothek.de/item/IDEYVAM52SZTJUSL347PX6JUIFR545ZD</identifier>
        <!-- Datum vom ingestDate -->
        <datestamp>2015-06-15T01:11:30Z</datestamp>
        <!-- Auflistung ALLER Sets in denen der Datensatz vorkommt -->
        <setSpec>5738807392711401XjYt</setSpec>
        <setSpec>5738807392711401XjYt_VSHJWG7QLS7Y3NS2HKE43E5Q5NJ7OCLS</setSpec>
        <setSpec>5738807392711401XjYt_mediatype_005</setSpec>
      </header>
      <metadata>
        <rdf:RDF 
          xmlns:edm="http://www.europeana.eu/schemas/edm/" 
          xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
          <!-- ... -->
        </rdf:RDF>
      </metadata>
    </record>
    <record>
      <!-- ... -->
    </record>
    <resumptionToken completeListSize="16240" cursor="0" expirationDate="2017-01-17T16:20:35Z">mCgPm-1042-0</resumptionToken>
  </ListRecords>
</OAI-PMH>

ListSets

URL	https://oai.deutsche-digitale-bibliothek.de?verb=ListSets
Parameter	resumptionToken (optional)	Token zur Wiederaufnahme bei größeren Datensets

Request

https://oai.deutsche-digitale-bibliothek.de?verb=ListSets

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?xml-stylesheet type='text/xsl' href='https://oai.deutsche-digitale-bibliothek.de/oai2.xsl'?>
<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>2017-01-12T13:51:56Z</responseDate>
  <request verb="ListSets">https://oai.deutsche-digitale-bibliothek.de/</request>
  <ListSets>
    <set>
      <setSpec>5738807392711401XjYt</setSpec>
      <setName>...</setName>
    </set>
    <set>
      <setSpec>5738807392711401XjYt_VSHJWG7QLS7Y3NS2HKE43E5Q5NJ7OCLS</setSpec>
      <setName>...</setName>
    </set>
    <set>
      <setSpec>5738807392711401XjYt_mediatype_005</setSpec>
      <setName>...</setName>
    </set>
    <set>
      <setSpec>BZVTR553HLJBDMQD5NCJ6YKP3HMBQRF4:subset-200001-300000</setSpec>
      <setName>...</setName>
    </set>
    <!-- ... -->
  </ListSets>
</OAI-PMH>

StatusCodes

Die OAI-Schnittstelle setzt HTTP-StatusCodes um.

200 - OK
503 - Service unavailable → Überlastung der Schnittstelle
429 - Too Many Requests → Überlastung der Schnittstelle
400 - Bad Request → OAI-ErrorConditions
404 - Not Found

HTTP compression

Die OAI-PMH-Schnittstelle der DDB unterstützt HTTP-Kompression gzip und br (Brotli). Siehe auch

Daten-Harvesting über die OAI-Schnittstelle der DDB

Strategie 1: ListRecords mit Set-Identifier

Set-Identifier: 5738807392711401XjYt (gesamtes Dataset)

Abfrage über Verb „ListRecords“: ?verb=ListRecords&metadataPrefix=edm&set=5738807392711401XjYt
Wiederholung mit resumptionToken bis das Ende erreicht ist: ?verb=ListRecords&resumptionToken=mCgPm-1073-0

Strategie 2: GetRecord über ListIdentifiers mit Set-Identifier

...