ZDB-Entitäten-API - Versionsgeschichte

Dbalzer: Beispiel-Key geändert

2022-05-03T13:42:48Z

Beispiel-Key geändert

Dbalzer: /* Beispiele für die Entitäten-API */

2022-04-30T18:18:39Z

‎Beispiele für die Entitäten-API

Dbalzer am 30. April 2022 um 18:11 Uhr

2022-04-30T18:11:33Z

Dbalzer am 30. April 2022 um 11:21 Uhr

2022-04-30T11:21:10Z

Dbalzer: /* ZDB-Entitäten-API */

2022-04-30T11:19:38Z

‎ZDB-Entitäten-API

Dbalzer: ausgelagert

2022-04-30T11:13:30Z

ausgelagert

Neue Seite

== ZDB-Entitäten-API ==

Eine [[API-Dienste ZDB-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.

<nowiki>https://ws.dff.film/zdb/p/489BF7038FAE48578CDBC01F2771A5B7?s=eac&xd=1&</nowiki>'''api_key=<span style="color:brown">DE61ZABMMjBj</span>'''

* 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: <span style="color:brown">DE61ZABMMjBj</span>"''' <nowiki>https://ws.dff.film/zdb/p/489BF7038FAE48578CDBC01F2771A5B7?s=eac&xd=1</nowiki>

=== 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:

<code><nowiki>https://ws.dff.film/zdb/</nowiki>'''p'''/489BF7038FAE48578CDBC01F2771A5B7</code> für einen Personen-Datensatz
<code><nowiki>https://ws.dff.film/zdb/</nowiki>'''ks'''/F1C924D0C54F43F59254D2560DCED123</code> für einen Körperschaftsdatensatz
<code><nowiki>https://ws.dff.film/zdb/</nowiki>'''fw'''/2760FD5E189F49D48E60F53EEA1C489B</code> 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''' - ''[https://eac.staatsbibliothek-berlin.de/ 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

:: '''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 ===

← Nächstältere Version		Version vom 30. April 2022, 18:18 Uhr
Zeile 68:		Zeile 68:

	== Beispiele für die Entitäten-API ==		== Beispiele für die Entitäten-API ==
		+
		+	Da diese Schnittstelle eine Autorisierung mit Zugangsschlüssel verlangt, können hier keine Live-Beispiele vorgestellt werden. Die Optionen zur Angabe des Schlüssels sind oben im Abschnitt "Zugangsbeschränkung" erläutert.

	<code><nowiki>https://ws.dff.film/zdb/fw/2760FD5E189F49D48E60F53EEA1C489B?api_key=</nowiki><span style="color:brown">{apiKey}</span>&s=dif-n</code>		<code><nowiki>https://ws.dff.film/zdb/fw/2760FD5E189F49D48E60F53EEA1C489B?api_key=</nowiki><span style="color:brown">{apiKey}</span>&s=dif-n</code>

← Nächstältere Version		Version vom 30. April 2022, 11:21 Uhr
Zeile 1:		Zeile 1:
−	Eine [[API-Dienste\|~~ZDB-~~API-Dienst]] zum Abruf von einzelnen Instanzen aus der ZDB in unterschiedlichen Datenformaten.	+	Eine Schnittstelle ([[API-Dienste\|API-Dienst]]) zum Abruf von einzelnen Instanzen aus der ZDB in unterschiedlichen Datenformaten.

	== Zugangsbeschränkung ==		== Zugangsbeschränkung ==

@@ Zeile 9: / Zeile 9: @@
 * 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.
-   <nowiki>https://ws.dff.film/zdb/p/489BF7038FAE48578CDBC01F2771A5B7?s=eac&xd=1&</nowiki>'''api_key=<span style="color:brown">DE61ZABMMjBj</span>'''
+   <nowiki>https://ws.dff.film/zdb/p/489BF7038FAE48578CDBC01F2771A5B7?s=eac&xd=1&</nowiki>'''api_key=<span style="color:brown">DE61ZABMMjBi</span>'''
 * 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: <span style="color:brown">DE61ZABMMjBj</span>"''' <nowiki>https://ws.dff.film/zdb/p/489BF7038FAE48578CDBC01F2771A5B7?s=eac&xd=1</nowiki>
+   curl '''-H "Apikey: <span style="color:brown">DE61ZABMMjBi</span>"''' <nowiki>https://ws.dff.film/zdb/p/489BF7038FAE48578CDBC01F2771A5B7?s=eac&xd=1</nowiki>
 == Basis-URL ==

@@ Zeile 39: / Zeile 39: @@
 * '''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.
+:: '''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.
@@ Zeile 67: / Zeile 67: @@
 * '''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 ==
+liefert den angebenen Personendatensatz im FORWARD-XML-Schema mit XML-Vorspann und zugeordneten Filmwerken. Da der Parameter <code>api_key</code> hier nicht gesetzt ist, muss beim Aufruf ein HTTP-Header mit dem Zugangsschlüssel gesendet werden.

@@ Zeile 1: / Zeile 1: @@
-== ZDB-Entitäten-API ==
+Eine [[API-Dienste|ZDB-API-Dienst]] zum Abruf von einzelnen Instanzen aus der ZDB in unterschiedlichen Datenformaten.
-Eine [[API-Dienste ZDB-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.
@@ Zeile 17: / Zeile 15: @@
    curl '''-H "Apikey: <span style="color:brown">DE61ZABMMjBj</span>"''' <nowiki>https://ws.dff.film/zdb/p/489BF7038FAE48578CDBC01F2771A5B7?s=eac&xd=1</nowiki>
-=== Basis-URL ===
+== 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:
@@ Zeile 25: / Zeile 23: @@
 <code><nowiki>https://ws.dff.film/zdb/</nowiki>'''fw'''/2760FD5E189F49D48E60F53EEA1C489B</code> für einen Filmwerksdatensatz
-=== Aufrufparameter ===
+== 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 ====
+=== 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
@@ Zeile 51: / Zeile 49: @@
 * '''api_key''' - Autorisierungsschlüssel als Aufrufparameter. Wird benötigt, wenn der Autorisierungsschlüssel nicht im HTTP-Header angegeben ist.
-==== Filmwerke ====
+=== Filmwerke ===
 * '''s''' - das Datenschema und  -format, in dem die angeforderten Daten geliefert werden sollen. Für Filmwerke sind dies
@@ Zeile 70: / Zeile 68: @@
-=== Beispiele für die Entitäten-API ===
+== Beispiele für die Entitäten-API ==