Sie sind hier: Startseite > API Documentation
1. Allgemeines
Für dieses Projekt wird neben der Web-Applikation timms-for-culture, welche in erster Linie für die Präsentation, das Management und den Upload von AV-Medien zuständig ist, auch eine API bereitgestellt. Die hier vorliegende Dokumentation, soll die Verwendung dieser API erläutern und den Aufbau der Metadaten beschreiben.
Zur Darstellung von Metadaten wird das XML-Schema PBCore verwendet. Dabei dient der PBCoreDescriptionDocument-Container für konkrete Medien-Objekte, um technische Metadaten abzubilden und mindestens die beschreibenden Daten für Titel, ID und Beschreibung anzugeben. Gegebenenfalls und falls vorhanden sind auch weitere beschreibende Metadaten mittels eines PBCorePart-Containers eingebunden.
Um ein bestimmtes Medien-Objekt zu kennzeichnen, wird eine abstrakte ID verwendet, welche dem Schema ZDV_[YYYYMMDD]_[6-stellige Zahlenfolge] folgt, also z.B. zdv_20240209_000001. Darüber hinaus wird der PBCoreCollection-Container verwendet, um einen Überblick über die vorhandenen Medien zu geben.
2. Abruf von Vorschaubild, Streaming- und Metadaten
Im Folgenden werden die Standardaufrufe erläutert, welche verwendet werden, um die Streamingdaten, die konkreten Metadaten und das Vorschaubild abzurufen.
2.1 Abrufen einer Playliste für das Streaming
Damit ein beliebiger HLS-fähiger Player ein Medien-Objekt streamen kann, benötigt dieser eine m3u8-Playlist. Diese kann mittels des folgenden Aufrufes unter Einfügung einer gültigen ZDV-ID abgerufen werden.
2.2 Abrufen eines Vorschaubildes
Wird ein Vorschaubild für ein Video benötigt, so wird dieses als JPG für jedes Medien-Objekt bereitgestellt. Der Aufruf soll die dem Medien-Objekt zugeordnete ZDV-ID enhalten.
2.3 Abrufen von Metadaten für ein konkretes Medien-Objekt
Werden die technischen und (falls vorhanden) beschreibende Metadaten benötigt, so werden diese als XML mit dem Schema PBCoreDescriptionDocument für jedes Medien-Objekt bereitgestellt. Dies geschieht mit dem folgenden Aufruf unter Einfügung einer gültigen ZDV-ID des Medien-Objekts.
3. Aufbau eines PBCoreDescriptionDocuments
Die Definion und Dokumentation von PBCore ist auf der offiziellen Seite des Projektes zu finden. Im Folgenden wird erläutert wie PBCore in diesem Projekt verwendet wird. Genauer gesagt, werden in diesem Kapitel Besonderheiten beschrieben, wie sie in einem PBCoreDescriptionDocument in diesem Projekt vorkommen.
Das Pflichtelement pbcoreIdentifier kann immer nur einfach vorhanden sein, um die Externe-ID des Medien-Objektes anzuzeigen. Das Attribut source gibt hier an, um welche Art von externer ID es sich handelt.
Im Folgenden ein Beispiel:
Das Pflichtelement pbcoreTitle ist immer einfach vorhanden und gibt den Titel des Medienobjektes wieder, wie im folgenden Beispiel zu sehen ist:
Das Pflichtelement pbcoreDescription muss vorhanden sein und enthält einen Wert, sofern einer gesetzt wurde, wie im folgenden Beispiel zu sehen ist:
Der Container pbcoreInstantiation ist kein Pflichtelement, wird aber in diesem Projekt in jedem
PBCoreDescriptionDocument mindestens zwei- und maximal dreimal verwendet.
Der erste pbcoreInstantiation-Container gibt dabei immer die technischen Metadaten des original
Medien-Objektes an. Zu erkennen ist dieser Container am Attribut source des Elementes
instantiationIdentifier, welches auf den Wert source="original" gesetzt wird.
Insofern ein Normalisierungsschritt stattgefunden hat, existiert ein pbcoreInstantiation Container, bei dem das Attribut source des instantiationIdentifier-Elements auf den Wert source="normalized" gesetzt ist.
Zu guter Letzt, muss es immer einen pbcoreInstantiation-Container geben, bei welchem das Attribut source
des instantiationIdentifier den Wert source="hls-master" hat.
Siehe dazu folgendes gekürztes Beispiel:
Insofern ergänzende beschreibende Metadaten bereitgestellt werden, werden diese mittels PBCorePart-Container angefügt. Dabei wird das Attribut source des Containers mit dem Wert source="ForeignOrganisationDescriptiveMetadata" gekennzeichnet, wie folgendes Beispiel zeigt:
4. Abruf einer Übersicht der verfügbaren Medien-Objekt
Um einen Überblick zu bekommen, welche AV-Objekte aktuell publiziert sind oder welche in den letzten 30 Tagen publiziert wurden, kann ein PBCoreCollection-Container abgefragt werden.
4.1 Abrufen der Übersicht über alle publizierten Medien-Objekte
Mit folgendem Aufruf, lässt sich eine PBCoreCollection abrufen, welche die aktuell verfügbaren Medienobjekte auflistet:
Im Folgenden ein Beispiel für eine PBCoreCollection:
Erläuterung des Aufbaus der PBCoreCollection
Die Anzahl der PBCoreDescriptionDocument-Container innerhalb der Collection entspricht den publizierten Medien Objekten.
Das Attribut source des PBCoreDescriptionDocument -Containers gibt den Kurznamen der veröffentlichenden Organisation an, z.B. source="LABW" für Landesarchiv Baden-Württemberg oder source="HDF" für Landesfilmsammlung.
Das Attribut ref des PBCoreDescriptionDocument-Containers
gibt den Pfad zum konkreten PBCoreDescriptionDocument des jeweiligen Medien-Objektes an, z.B.
Das Attribut annotation des PBCoreDescriptionDocument-Containers gibt an, ob das Medien-Objekt über zusätzliche beschreibende Metadaten verfügt oder nicht. Die Werte annotation=„descriptive metadata available“ und annotation=„no descriptive metadata available“ sind dabei selbsterklärend. Das Pflichtelement pbcoreIdentifier ist jeweils doppelt vorhanden, um sowohl die ZDV-ID als auch die Externe-ID des Medienobjektes anzuzeigen, wie das folgende Beispiel zeigt:
Das Pflichtelement pbcoreTitle ist jeweils einfach vorhanden und gibt den Titel des Medien-Objektes an, wie im folgenden Beispiel zu sehen ist:
Das Pflichtelement pbcoreDescription ist obligatorisch, wird in der Collection aber nicht gesetzt. Der konkrete Inhalt lässt sich aus dem zugehörigen PBCoreDescriptionDocument auslesen.
Das Element instantiationDate wird verwendet, um das Upload-Datum des jeweiligen Medien-Objektes anzugeben, wobei das Attribut dateType immer auf den Wert „upload“ gesetzt ist und das Datum der Notation YYYY-MM-DD folgt:
Das Pflichtelement instantiationLocation ist obligatorisch, wird hier aber nicht gesetzt. Der konkrete Inhalt lässt sich aus dem zugehörigen PBCoreDescriptionDocument auslesen.
Das Element instantiationMediaType wird verwendet, um die Art des Medientyps anzugeben (z.B. ob es sich um ein Video oder ein Audio handelt).
4.2 Abrufen der Übersicht über alle publizierten Medien-Objekte der letzten 30-Tage
Mit folgendem Aufruf, lässt sich eine PBCoreCollection abrufen, welche die aktuell verfügbaren Medienobjekte auflistet:
Erläuterung des Aufbaus der PBCoreCollection
Der Aufbau der PBCoreCollection ist in diesem Fall analog zum Aufbau der PBCoreCollection für die Anzeige aller publizierter Medien-Objekte. Es ist lediglich zu beachten, dass, wenn es innerhalb der letzten 30Tage keine neuen Inhalte gab, eine leere PBCoreCollection angezeigt wird, wie im folgenden Beispiel zu sehen ist:
5. Abruf einer Übersicht verschiedener Kategorien
Es ist möglich, die verfügbaren Medien-Objekte wahlweise nach Provenienz oder Organisation zu filtern. Dazu kann jeweils ein PBCoreCollection-Container abgefragt werden, die alle verfügbaren Provenienzen oder alle Organisationen auflistet, welche Medien-Objekte bereitstellen.
5.1. Abrufen einer Übersicht der verfügbaren Provenienzen
Mit folgendem Aufruf, lässt sich eine PBCoreCollection abrufen, welche die aktuell verwendeten Provenienzen auflistet:
Erläuterung des Aufbaus der PBCoreCollection
Die PBCoreCollection besteht aus einer Anzahl von PBCoreDecriptionDocument-Containern, welche der Anzahl der verfügbaren Provenienzen entspricht. Dabei ist der PBCoreDescriptionDocument-Container minimal groß. Das pbcoreIdentifier-Element hat immer das source-Attribut mit dem Wert source="provenance_id“ und als Inhalt eine ID, welche zum Suchen nach Medien-Objekten, die diese ID enthalten, verwendet werden kann. Das pbcoreTitle-Element hat immer ein annotation-Attribut mit dem Wert annotation="provenance" und als Inhalt den Namen der Provenienz. Im Folgenden ein Beispiel dazu:
5.2 Abrufen einer Übersicht der verfügbaren Organisationen
Mit folgendem Aufruf, lässt sich eine PBCoreCollection abrufen, welche die aktuell publizierende Organisationen auflistet:
Erläuterung des Aufbaus der PBCoreCollection
Die PBCoreCollection besteht aus einer Anzahl von PBCoreDecriptionDocument-Containern, welche der Anzahl der verfügbaren Organisationen entspricht. Der einzelne pbcoreDescriptionDocument-Container hat dabei jeweils ein source-Attribut, das als Wert den Kurznamen der zugehörigen Organisation hat. Das pbcoreIdentifier-Element hat immer das source-Attribut mit dem Wert source="organisation_id“ und als Inhalt eine ID, welche zum Suchen nach Medien-Objekten verwendet werden kann. Das pbcoreTitle-Element ist doppelt vorhanden. Einmal hat es ein annotation-Attribut mit dem Wert annotation=" abbreviation" und als Inhalt den Kurznamen der Organisation. Das andere pbcoreIdentifier-Element hat ein annotation-Attribut mit dem Wert annotation="fullName" und als Inhalt den vollen Namen der Organisation. Im Folgenden ein Beispiel dazu:
6. Abruf einer Liste von AV-Objekten nach Kategorie
Es ist möglich, die verfügbaren Medien-Objekte wahlweise nach Provenienz oder Organisation zu filtern. Dazu wird im ersten Schritt eine ID benötigt, welche wie hier beschrieben abgefragt werden kann. Mit dieser ID lässt sich anschließend ein PBCoreCollection-Container abfragen, welcher alle Medien-Objekte auflistet, die der ID entsprechen.
6.1 Abrufen aller publizierten Medien-Objekte mit einer bestimmten Provenienz-ID
Folgender Aufruf liefert eine PBCoreCollection, welche alle publizierten Medien-Objekte enthält, die mit einer bestimmten Provenienz verknüpft sind:
Erläuterung des Aufbaus der PBCoreCollection
Der Aufbau dieser PBCoreCollection ist analog zum Aufbau der PBCoreCollection für die Anzeige aller publizierter Medien-Objekte. Es ist lediglich zu beachten, dass, wenn die angegebene Provenienz-ID nicht vergeben ist, eine leere PBCoreCollection zurückgegeben wird.
6.2 Abrufen der Übersicht über alle publizierten Medien-Objekte einer Organisation
Mit folgendem Aufruf, lässt sich eine PBCoreCollection abrufen, welche alle publizierten Medien-Objekte enthält, die mit einer bestimmten Organisation verknüpft sind:
Erläuterung des Aufbaus der PBCoreCollection
Der Aufbau der PBCoreCollection ist analog zum Aufbau der PBCoreCollection für die Anzeige aller publizierter Medien-Objekte. Es ist lediglich zu beachten, dass, wenn die angegebene Provenienz-ID nicht vergeben ist, eine leere PBCoreCollection zurückgegeben wird.