API-Dokumentation

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.

{server-url}/Media/GetHLS/{zdv-id}/masterplaylist.m3u8

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 enthalten.

{server-url}/Media/GetPoster/{zdv-id}/poster.jpg

2.3 Abrufen von Metadaten für ein konkretes Medien-Objekt

Werden die technischen und (falls vorhanden) beschreibenden 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.

{server-url}/Meta/GetPBCore/{zdv-id}/pbcore.xml

3. Aufbau eines PBCoreDescriptionDocuments

Die Definition 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.

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: 

<pbcoreIdentifier source="fesad_id">LFS000143</pbcoreIdentifier>

Das Pflichtelement pbcoreTitle ist immer einfach vorhanden und gibt den Titel des Medienobjektes wieder: 

<pbcoreTitle>Schützenfest Biberach 1934</pbcoreTitle>

Das Pflichtelement pbcoreDescription muss vorhanden sein und enthält einen Wert, sofern einer gesetzt wurde: 

<pbcoreDescription>Maienfest in Göppingen 1929.</pbcoreDescription>

Der Container pbcoreInstantiation ist kein Pflichtelement, wird aber in diesem Projekt in jedem PBCoreDescriptionDocument mindestens zwei- und maximal dreimal verwendet:

  • source="original" — technische Metadaten des Original-Medien-Objektes
  • source="normalized" — falls ein Normalisierungsschritt stattgefunden hat
  • source="hls-master" — muss immer vorhanden sein
<pbcoreInstantiation>
  <instantiationIdentifier source="original">test.mpeg</instantiationIdentifier>
  …
</pbcoreInstantiation>
<pbcoreInstantiation>
  <instantiationIdentifier source="normalized">test.mp4</instantiationIdentifier>
  …
</pbcoreInstantiation>
<pbcoreInstantiation>
  <instantiationIdentifier source="hls-master">zdv_20221017_000027.m3u8</instantiationIdentifier>
  …
</pbcoreInstantiation>

Ergänzende beschreibende Metadaten werden über einen PBCorePart-Container angefügt. Das Attribut source wird dabei auf "ForeignOrganisationDescriptiveMetadata" gesetzt.

4. Übersicht der verfügbaren Medien-Objekte

Um einen Überblick zu bekommen, welche AV-Objekte aktuell publiziert sind, kann ein PBCoreCollection-Container abgefragt werden.

4.1 Alle publizierten Medien-Objekte

Mit folgendem Aufruf lässt sich eine PBCoreCollection abrufen, welche die aktuell verfügbaren Medienobjekte auflistet:

{server-url}/Meta/GetPBCoreCollection

Im Folgenden ein Beispiel für eine PBCoreCollection:

<pbcoreCollection xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns="http://www.pbcore.org/PBCore/PBCoreNamespace.html">
  <pbcoreDescriptionDocument source="HDF"
        ref="https://timms17.v294.uni-tuebingen.de/Meta/GetPBCore/zdv_20240110_000009/pbcore.xml"
        annotation="descriptive metadata available">
    <pbcoreIdentifier source="zdv_id">zdv_20240110_000009</pbcoreIdentifier>
    <pbcoreIdentifier source="fesad_id">LFS000143</pbcoreIdentifier>
    <pbcoreTitle>Schützenfest Biberach 1934</pbcoreTitle>
    <pbcoreDescription />
    <pbcoreInstantiation>
      <instantiationIdentifier source="" />
      <instantiationDate dateType="upload">2024-01-10</instantiationDate>
      <instantiationLocation />
      <instantiationMediaType>video</instantiationMediaType>
    </pbcoreInstantiation>
  </pbcoreDescriptionDocument>
  …
</pbcoreCollection>

Erläuterung des Aufbaus:

  • Das Attribut source nennt den Kurznamen der Organisation (z. B. LABW, HDF).
  • ref verweist auf das vollständige PBCoreDescriptionDocument.
  • annotation ist entweder "descriptive metadata available" oder "no descriptive metadata available".
  • pbcoreIdentifier ist doppelt vorhanden (ZDV-ID + externe ID).
  • instantiationDate trägt das Upload-Datum (Format YYYY-MM-DD).
  • instantiationMediaType gibt z. B. video oder audio an.

4.2 Publizierte Medien-Objekte der letzten 30 Tage

Aufruf für die Übersicht der jüngsten Veröffentlichungen:

{server-url}/Meta/GetLatestPBCoreCollection

Der Aufbau ist analog zu 4.1. Sind in den letzten 30 Tagen keine neuen Inhalte erschienen, wird eine leere PBCoreCollection zurückgegeben.

5. Übersicht verschiedener Kategorien

Die verfügbaren Medien-Objekte können wahlweise nach Provenienz oder Organisation gefiltert werden. Dazu lässt sich jeweils ein PBCoreCollection-Container abfragen.

5.1 Verfügbare Provenienzen

{server-url}/Meta/GetAvailableProvenances

Jeder PBCoreDescriptionDocument-Container besitzt einen pbcoreIdentifier mit source="provenance_id" (numerische ID) sowie einen pbcoreTitle mit annotation="provenance" (Name der Provenienz): 

<pbcoreDescriptionDocument>
  <pbcoreIdentifier source="provenance_id">4</pbcoreIdentifier>
  <pbcoreTitle annotation="provenance">Baresel AG</pbcoreTitle>
  <pbcoreDescription />
</pbcoreDescriptionDocument>

5.2 Verfügbare Organisationen

{server-url}/Meta/GetAvailableOrganisations

Jeder pbcoreDescriptionDocument-Container hat ein source-Attribut (Kurzname). Der pbcoreIdentifier trägt source="organisation_id"; pbcoreTitle ist zweifach vorhanden (Kurzname und vollständiger Name): 

<pbcoreDescriptionDocument source="LABW">
  <pbcoreIdentifier source="organisation_id">1</pbcoreIdentifier>
  <pbcoreTitle annotation="abbreviation">LABW</pbcoreTitle>
  <pbcoreTitle annotation="fullName">Landesarchiv Baden-Württemberg</pbcoreTitle>
  <pbcoreDescription />
</pbcoreDescriptionDocument>

6. Liste von AV-Objekten nach Kategorie

Mit einer aus Abschnitt 5 ermittelten ID lässt sich anschließend eine PBCoreCollection mit allen passenden Medien-Objekten abrufen.

6.1 Alle Medien-Objekte einer Provenienz

{server-url}/Meta/GetPBCoreCollectionByProvenanceId/{provenanceId}

Der Aufbau ist analog zu 4.1. Ist die angegebene Provenienz-ID nicht vergeben, wird eine leere PBCoreCollection zurückgegeben.

6.2 Alle Medien-Objekte einer Organisation

{server-url}/Meta/GetPBCoreCollectionByOrganisationId/{organisationId}

Der Aufbau ist analog zu 4.1. Ist die angegebene Organisations-ID nicht vergeben, wird eine leere PBCoreCollection zurückgegeben.