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.

Personen- und Körperschaftsdaten aus der DFF-ZDB

Zugangsbeschränkung

Zum Abruf von Personen- und Körperschaftsdatensä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 autimatisierte 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" und für Körperschaften das Kürzel "ks", 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

Aufrufparameter

In den meisten Fällen wird es nötig sein, einen oder mehrere der folgenden Aufrufparameter zu verwenden:

  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 - Keine Präambel, sondern reine XML-Daten ab dem Wurzelement für den Datensatz. Geeignet für Mehrfach-Abfragen, deren Ergebnisse 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.