ZDB-Entitäten-API

Eine Schnittstelle (API-Dienst) 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&api_key=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 - (voreingestellt) 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

dif-n - Das native XML-Format für Filmwerke der ZDB in der Version 1.4.

dif-n1.5 - Das native XML-Format für Filmwerke der ZDB in der Version 1.5. Reihen- und Gesamttitel werden hier zu einer Entität "Aggregatwerk".

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

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

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

Beispiele für die Entitäten-API

https://ws.dff.film/zdb/fw/2760FD5E189F49D48E60F53EEA1C489B?api_key={apiKey}&s=dif-n

liefert den angegebenen Filmwerk-Datensatz im nativen XML-Schema, Version 1.4, ohne XML-Vorspann (xd=0 ist implizit).

https://ws.dff.film/zdb/ks/9256CBE1A4324F3E9A4F73D616468CD7?api_key={apiKey}&s=eac&xd=1

liefert den angebenen Körperschaftsdatensatz im EAC-Schema mit XML-Vorspann.

https://ws.dff.film/zdb/p/9256CBE1A4324F3E9A4F73D616468CD7?s=forward&xd=1&add=FW

liefert den angebenen Personendatensatz im FORWARD-XML-Schema mit XML-Vorspann und zugeordneten Filmwerken. Da der Parameter api_key hier nicht gesetzt ist, muss beim Aufruf ein HTTP-Header mit dem Zugangsschlüssel gesendet werden.