API-Dienste

APIs (Application Program Interfaces) werden für die programmgestützte Nutzung bereitgestellt. Hierüber können Kooperationspartner des DFF mit ihren Anwendungsprogrammen Daten aus dem Bestand der ZDB abrufen.

Der Zugang erfolgt über die Subdomain ws.dff.film, mit Ausnahme der Dienste, die das Protokoll OAI-PMH (Open Archive Initiative Protocol for Metadata Harvesting) verwenden. Für letztere gibt es die Subdomain oai.dff.film.

ZDB-Entitäten-API

Eine Schnittstelle zum Abruf von einzelnen Instanzen aus der ZDB in unterschiedlichen Datenformaten.

Zugangsbeschränkung

Zum Abruf von Personen- und Körperschafts- und Filmwerksdatensätzen wird ein Zugangsschlüssel (API Key) benötigt. Dieser wird im Rahmen von Kooperationsvereinbarungen durch die Digitale Abteilung des DFF zugeteilt. Die in den nachfolgenden Beispielen verwendeten Zugangsschlüssel sind nicht gültig und müssen für den Gebrauch durch einen gültigen Schlüssel ersetzt werden.

Alle hier dokumentierten Aufrufe können auf eine der folgenden Arten autorisiert werden:

• Durch Angabe eines URL-Parameters "api_key" mit dem Schlüssel als Wert. Diese Variante eignet sich sowohl für Aufrufe aus einem Web-Browser wie auch für automatisierte Abfragen.

 https://ws.dff.film/zdb/p/489BF7038FAE48578CDBC01F2771A5B7?s=eac&xd=1&apikey=DE61ZABMMjBj

• Durch Angabe eines HTTP-Headers "Apikey" mit dem Schlüssel als Wert. Diese Variante eignet sich vorrangig für automatisierte Abfragen durch Client-Programme. Mit einem Kommendozeilen-Werkzeug wie curl sieht eine solche Abfrage folgendermaßen aus:

 curl -H "Apikey: DE61ZABMMjBj" https://ws.dff.film/zdb/p/489BF7038FAE48578CDBC01F2771A5B7?s=eac&xd=1

Basis-URL

Alle Aufrufe haben die Basis-Adresse https://ws.dff.film/zdb/ . Für die Entität "Person" folgt das Kürzel "p", für Körperschaften "ks" und für Filmwerke "fw", gefolgt vom UID des gewünschten Datensatzes:

https://ws.dff.film/zdb/p/489BF7038FAE48578CDBC01F2771A5B7 für einen Personen-Datensatz https://ws.dff.film/zdb/ks/F1C924D0C54F43F59254D2560DCED123 für einen Körperschaftsdatensatz https://ws.dff.film/zdb/fw/2760FD5E189F49D48E60F53EEA1C489B für einen Filmwerksdatensatz

Aufrufparameter

In den meisten Fällen wird es nötig sein, einen oder mehrere der folgenden Aufrufparameter als angehängte Option(en) zum Basis-URL zu verwenden:

Personen und Körperschaften

• s - das Datenschema und -format, in dem die angeforderten Daten geliefert werden sollen. Für Personen und Körperschaften sind dies

eac - Encoded Archival Context for Corporate Bodies, Persons, and Families. Ein geringfügig modifiziertes XML-Schema von der Gemeinschaft der Archivare.

forward - XML-Schema für das ehemalige Projekt FORWARD.

dnb_json - JSON-Format, wie für die Datenübertragung an die GND verwendet.

• xd - Nur für XML-basierte Formate: Voranstellen einer Präambel mit XML processing instruction und der Schema-Referenz. Boolesches Attribut mit den Werten 0 (nein) und 1 (ja).

0 - Ohne Präambel, d.h. reine XML-Daten ab dem Wurzelement für den Datensatz. Geeignet für Mehrfach-Abfragen, deren Ergebnisse beim Client zu einem XML-Dokument zusammengeführt werden sollen.

1 - Mit Präambel. Geeignet für Abfragen, die einzeln mit XML-Werkzeugen verarbeitet werden sollen.

• add - Einbeziehen von verknüpften Entitäten. Derzeit nur verfügbar für Personen-Datensätze im EAC-XML-Format.

FW - Verknüpfte Filmwerke mit Angabe der Funktion bzw. Rolle werden in Kurzdarstellung an den Personen-Datensatz angefügt.

• api_key - Autorisierungsschlüssel als Aufrufparameter. Wird benötigt, wenn der Autorisierungsschlüssel nicht im HTTP-Header angegeben ist.

Filmwerke

• s - das Datenschema und -format, in dem die angeforderten Daten geliefert werden sollen. Für Filmwerke sind dies