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: Abfragen mehrerer Datensätze
ListSets: Abfragen vorhandener Sets

URLs

Produktion: https://oai.deutsche-digitale-bibliothek.de/
Entwicklung: https://dev-ddb.fiz-karlsruhe.de/oai/ (testsystem/testsystem)

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 (ID). 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. Einstweilen werden OAI-Datensetz wie u.g eindeutig identifiziert.

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

OAI-Datensets

Lieferung an Europeana

Die OAI-Datensets werden nach folgenden Kriterien gebildet.

Kriterium	Benennung des Datensets	Kommentar	Beispiele (in Solr-Query-Syntax)
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/"

Element	Term	URI
mediatype_001	Audio	http://ddb.vocnet.org/medientyp/mt001
mediatype_002	Image	http://ddb.vocnet.org/medientyp/mt002
mediatype_003	Text	http://ddb.vocnet.org/medientyp/mt003
mediatype_004	Full-Text	http://ddb.vocnet.org/medientyp/mt004
mediatype_005	Video	http://ddb.vocnet.org/medientyp/mt005
mediatype_006	Others	http://ddb.vocnet.org/medientyp/mt006
mediatype_007	No media type	http://ddb.vocnet.org/medientyp/mt007
mediatype_008	Institution	http://ddb.vocnet.org/medientyp/mt008

Element	Term
rights_001	Lizenzgruppe 1
rights_002	Lizenzgruppe 2
rights_003	Lizenzgruppe 3

siehe auch https://dev.fiz-karlsruhe.de/stash/projects/DDB/repos/ddb-mapping-new/browse/opt/transformationdir/conf/concordance/common/license_group.xml

Anforderungen

Allgemein

Das Harvesting einzelner DDB-IDs ist über die Methode GetRecord möglich.
- z. B. https://oai.deutsche-digitale-bibliothek.de?verb=GetRecord&metadataPrefix=edm&identifier=IDEYVAM52SZTJUSL347PX6JUIFR545ZD
Veränderungen innerhalb einen OAI-Datensets über die Zeit können durch einen Timestamp abfragbar sein.
- z. B. https://oai.deutsche-digitale-bibliothek.de?verb=ListIdentifiers&metadataPrefix=oai_dc&from=2020-01-01&set=5738807392711401XjYt
Deleted Records werden gemäß der OAI/PMH-Spezifikation unterstützt.
- siehe http://www.openarchives.org/OAI/openarchivesprotocol.html#DeletedRecords
Das Löschen von OAI-Sets ist zunächst nicht vorgesehen, da es eine komplette Neuindexierung notwendig macht. Das ist bisher nicht implementiert.

Blacklisting und Whitelisting

Der (kooperations-) vertragliche Zusammenhang von Europeana-Weitergabe und API-Blacklisting hat keine Auswirkungen auf die OAI-Schnittstelle. 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. Die weitere Klärung obliegt DDB/DNB bzw. SSt.
Eine Freischaltung auf dem OAI-Server (Whitelisting) ist nicht vorgesehen. Jedes DDB-Objekt bekommt auf dem OAI-Server einen OAI/DC-Datensatz, der erst einmal nur die DDB-ID enthält.

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.
Konfiguration der OAI-Schnittstelle (Logo: DDBpro_Logo_2_s_pos_RGB_G.svg oder DDBpro_Logo_2_s_pos_RGB_G.png oder DDBpro_Logo_2_s_pos_RGB_G_BG.jpg)
Anzahl der Objekte in einem Request: 300 (konfigurierbar in der Server-konfiguration bis max 1.000)
Gültigkeit der Resumption-Token: theoretisch ewig (Verwendung der Cursor-Funktionalität von SOLR)
- Bei einem Update während des Harvestings: Da nach Datum aufsteigend sortiert wird werden geänderte Objekte ans Ende der Liste sortiert und werden ggf. zuletzt noch einmal ausgeliefert.

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

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=IDEYVAM52SZTJUSL347PX6JUIFR545ZD

<?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="IDEYVAM52SZTJUSL347PX6JUIFR545ZD" 
    metadataPrefix="edm" 
    verb="GetRecord">https://oai.deutsche-digitale-bibliothek.de/</request>
  <GetRecord>
    <record>
      <header>
        <identifier>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>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>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>
    <!-- ... -->
  </ListSets>
</OAI-PMH>

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

...