Auf dieser Seite werden gebündelt Dienste zu den dMGH angeboten. Diese Seite ist in der jetzigen Form experimentell, kann jederzeit geändert werden und auch die Adresse wird sich in naher Zukunft ändern. Alle hier angebotenen Dienste befinden sich im Beta-Stadium. Bei Fragen wenden Sie sich bitte an Clemens Radl.
Über das Hauptangebot der dMGH sind die Editionsbände der MGH zugänglich. Derzeit werden diese lediglich als Bilder präsentiert. Ein Prototyp der Volltextsuche wird in diesen Tagen eingerichtet.
Bei der Arbeit an dem dMGH-Projekt fallen weitere Daten an, die mit der hauptsächlichen Präsentationssoftware nicht ohne weiteres zugänglich gemacht werden können. Diese können aber trotzdem für die Benutzung sinnvoll sein. So werden MGH-Bände in der Regel mit gängigen Abkürzungen zitiert. Wünschenswert ist hier beispielsweise eine Möglichkeit der Abkürzungsauflösung bzw. der direkten Verlinkung unter Angabe des Bandes und der Seitenzahl.
Manche Informationen betreffen auch nicht das gesamte Quellencorpus, sondern können lediglich für bestimmte Editionstypen sinnvoll angewendet werden. Bei Urkundeneditionen sollte auch eine Zitierung nach Herrschernamen und Urkundennummer möglich sein.
Auf dieser Seite sollen derartige Dienste gebündelt werden. Die Schnittstellen, mit denen sie genutzt werden können, werden dokumentiert. Es werden mehrere verschiedene Möglichkeiten geboten, wie man auf die Schnittstelle zugreifen kann. Im folgenden werden im Abschnitt API-Definition allgemein die Funktionen vorgestellt, die die Schnittstelle bietet. Zu den Namen der Funktionen wird angegeben, welche Werte der Funktion beim Aufruf übergeben werden müssen und wie die Rückgabewerte zu interpretieren sind.
In den weiteren Abschnitten werden verschiedene Wege aufgezeigt, wie man die API konkret nutzen kann. Hier finden Sie die technische Beschreibung, wie die Parameter und die Rückgabewerte übergeben werden müssen.
Angeboten werden zwei auf CGI basierende Schnittstellen. Die eine funktioniert wie klassisches CGI: Sie geben die Funktionsparameter in ein Webformular ein und als Ergebnis erhalten Sie eine HTML-Seite, in der die Ergebnisse präsentiert werden. Dies ist primär für die interaktive Nutzung direkt am Browser geeignet. Für eine maschinelle, programmgesteuerte Weiterverarbeitung empfiehlt sich die REST-Schnittstelle. (REST steht für Representational State Transfer. Hinweise zu den Prinzipien von REST bei Wikipedia.) Die Parameterübergabe erfolgt wie oben durch einen GET-Request an eine bestimmte URL. Als Ergebnis erhält man aber keine HTML-Datei, die für den menschlichen Benutzer am Monitor geeignet ist, sondern eine XML-Datei, die einfacher maschinell weiterverarbeitet werden kann.
Als dritte Möglichkeit gibt es noch den standardisierten Zugriff über SOAP (vgl. wiederum SOAP bei Wikipedia). SOAP bietet die Möglichkeit, die API-Funktionsaufrufe direkt in die eigenen Programme einzubinden. Die Übergabe komplexer Parameter und Rückgabewerte erfolgt mittels XML-Dateien, die dem SOAP-Standard genügen. Bei Verwendung einer der zahllosen SOAP-Bibliotheken für die jeweilige Programmiersprache, kann man die explizite Erzeugung und Auswertung von XML-Nachrichten verzichten, da die SOAP-Bibliothek diese automatisch in Konstrukte der jeweiligen Programmiersprache übersetzt. Hinweis: Die SOAP-Schnittstelle ist momentan noch die am wenigsten ausgearbeitete Schnittstelle der dMGH. Rückmeldungen über die Verwendbarkeit und vor allem über Probleme mit einzelnen Programmiersprachen und SOAP-Bibliotheken sind erwünscht.
Der Ausbau dieser Programmierschnittstelle hängt entscheidend von der Rückmeldung der Benutzer ab. Falls Bedarf besteht, können an dieser Stelle auch kurze, prägnante Programmier-Beispiele hinterlegt werden. Beiträge von Nutzern sind hochwillkommen.
Ein wichtiger Hinweis: Diese Seite und alle hier beschriebenen und verlinkten Dienste befinden sich noch im Beta-Stadium und können daher jederzeit Änderungen unterworfen sein. Insbesondere ist die URL dieser Seite noch als provisorisch zu verstehen. In absehbarer Zeit wird sie auf eine andere Adresse umziehen. Dies betrifft dann auch die URLs der hier beschriebenen Web-Services.
Liefert als Zeichenkette die Version der API als Zeichenkette zurück. Eine Versionsnummer besteht aus drei Bestandteilen, die durch Punkte voneinander getrennt sind. Die erste Zahl gibt die Hauptversion an. Wenn sich die API grundlegend ändert, sodass Inkompatibilitäten zu früheren Versionen zu erwarten sind, wird die Hauptnummer erhöht. Der zweite Bestandteil ist die Versionsnummer. Diese wird erhöht, wenn es signifikante Erweiterungen der API gibt. Solange sich die Hauptnummer nicht ändert, sollten allerdings Programme, die auf einer älteren Version basieren dennoch voll lauffähig bleiben. Die dritte Nummer schließlich wird verändert, wenn es Korrekturen und Bugfixes gibt, die aber die Schnittstelle nicht verändern.
Programme im Produktionsbetrieb sollten zumindest die Hauptversionsnummer mit der Versionsnummer vergleichen, mit der sie geschrieben wurden. Falls die zurückgelieferte Hauptversionsnummer höher ist als die Nummer, für die das Programm geschrieben wurde, ist mit Inkompatibilitäten zu rechnen.
Die derzeitige Version der API ist 0.1.0.
Bemerkung: Diese Versionsangabe bezieht sich lediglich auf die Version der API und deren Funktionalität. Die dahinter liegenden Kernmodule und die Datenbank, aus der die Resultate gewonnen werden, können unabhängig von der API-Version geändert werden. Das gleiche gilt für die Dokumentation und in der Anfangsphase auch für die URLs, unter denen die Dienste zu erreichen sind.
Nimmt einen beliebigen String als Argument und liefert eine Liste von BSB-Nummern (= Datenbank-IDs) zurück. Jede dieser Nummern steht für einen MGH-Band, der als Digitalisat vorliegt. Aus dieser Nummer könnte bereits ein Link zu dem entsprechenden Band innerhalb der dMGH erzeugt werden. Für diesen Vorgang existieren allerdings auch Funktionsaufrufe innerhalb der API. Es wird geraten, den API-Aufruf zur Linkerzeugung zu verwenden, denn nur so kann bei etwaigen Linkänderungen gewährleistet werden, dass die korrekte Ressource gefunden wird.
Diese Funktion versucht, möglichst umfassend den Datenbestand zu durchsuchen, um möglichst viele passende Bände zu finden. Hierbei werden derzeit exakte Treffer nicht besonders privilegiert. Das bedeutet: Eine Suche nach "MGH SS 1" findet nicht nur den Band "Scriptores in Folio 1", sondern auch die Bände "Scriptores in Folio 10" bis "Scriptores in Folio 19", weil in den Kurztiteln aller dieser Bände die Zeichenkette "MGH SS 1" vorkommt (also beispielsweise MGH SS 12). Durchsucht werden die Felder "Kurztitel" (= MGH spezifische abgekürzte Zitierweise, vgl. den Navigationsbaum der dMGH-Webseite), "Autor" (Nachname, Vorname), "Erscheinungsjahr", "Titel".
Argumente: BSB-Nummer und gewünschte Seitenzahl
Diese Methode findet zu einem gegebenen Band (repräsentiert durch die BSB-Nummer) und der darin gesuchten Seitenzahl (die so angegeben werden sollte, wie sie im Buch verzeichnet ist) die zugehörige Bildnummer.
Mit Hilfe der BSB-Nummer und der Image-Nummer kann ein Link zum Digitalisat der jeweiligen Seite erzeugt werden. Es wird geraten, den API-Aufruf zur Linkerzeugung zu verwenden, denn nur so kann bei etwaigen Linkänderungen gewährleistet werden, dass die korrekte Ressource gefunden wird.
Benötigt als Argument mindestens eine BSB-Nummer. Wird auch noch die optionale Bildnummer angegeben, so wird ein Link zu genau der betreffenden Seite erzeugt.
Benötigt als Argument einen Suchstring, der eine Urkunde in der üblichen Kurzzitierweise bezeichnet, also beispielsweise "D O I 23". Zurückgeliefert wird ein Link auf die Edition der betreffenden Urkunde.
Diese Methode ist noch experimentell und beruht noch nicht auf einer durchkorrigierten Datenbasis. Sie dient lediglich zu Demonstrationszwecken.
| URL: | http://www.clemens-radl.de/cgi-bin/dmgh/startrest.sh?method=get_API_version |
| URL: | http://www.clemens-radl.de/cgi-bin/dmgh/startrest.sh?method=resolve&s=<Suchzeichenkette> |
Beachten Sie bitte, dass – wie bei allen REST-Aufrufen der dMGH-API – die Zeichenkette Sonderzeichen enthalten darf. Diese müssen allerdings in UTF-8 kodiert sein. Das unten stehende Formular erzeugt die korrekten Kodierungen.
| URL: | http://www.clemens-radl.de/cgi-bin/dmgh/startrest.sh?method=get_img_num&bsb=<BSB-Nummer>&page=<Seitennummer> |
| URL: | http://www.clemens-radl.de/cgi-bin/dmgh/startrest.sh?method=create_link&bsb=<BSB-Nummer>&img=<Bildnummer> |
| URL: | http://www.clemens-radl.de/cgi-bin/dmgh/startrest.sh?method=get_charter&s=<Urkundenkürzel> |
| URL: | http://www.clemens-radl.de/cgi-bin/dmgh/startcgi.sh?method=get_API_version |
| URL: | http://www.clemens-radl.de/cgi-bin/dmgh/startcgi.sh?method=resolve&s=<Suchzeichenkette> |
Beachten Sie bitte, dass – wie bei allen CGI-Aufrufen der dMGH-API – die Zeichenkette Sonderzeichen enthalten darf. Diese müssen allerdings in UTF-8 kodiert sein. Das unten stehende Formular erzeugt die korrekten Kodierungen.
| URL: | http://www.clemens-radl.de/cgi-bin/dmgh/startcgi.sh?method=get_img_num&bsb=<BSB-Nummer>&page=<Seitennummer> |
| URL: | http://www.clemens-radl.de/cgi-bin/dmgh/startcgi.sh?method=create_link&bsb=<BSB-Nummer>&img=<Bildnummer> |
| URL: | http://www.clemens-radl.de/cgi-bin/dmgh/startcgi.sh?method=get_charter&s=<Urkundenkürzel> |
Die URL für die SOAP-Schnittstelle lautet http://www.clemens-radl.de/cgi-bin/dmgh/startsoap.sh
Bislang werden in der Schnittstelle lediglich einfache Datentypen zwischen Client und Server ausgetauscht, sodass noch nicht zwingend die Notwendigkeit für die Verwendung einer WSDL-Datei, in der die Funktionen und die zu übergebenden Datentypen bestimmt werden, besteht. In Zukunft wird an dieser Stelle eine WSDL-Datei zur Verfügung gestellt werden und somit eine maschinenlesbare Definition der Schnittstelle existieren.
Die SOAP-Schnittstelle wurde getestet mit SOAP-Bibliotheken der Programmiersprache Python (ZSI und SOAP.py). Einfache Tests wurden auch mit PERL (SOAP::Lite) durchgeführt. Die Tests mit PHP hingegen konnten noch nicht erfolgreich durchgeführt werden.
Insbesondere in diesem Bereich sind wir auf Rückmeldungen angewiesen, um abschätzen zu können, inwieweit die Weiterentwicklung von dieser Schnittstelle erfolgen soll und auf welche Programmiersprachen und Programmbibliotheken vorrangig getestet werden soll.
Hier sind Dienste denkbar, die ein leichteres Verlinken auf Einzelseiten ermöglichen. Denkbar wäre zum Beispiel, dass URLs der Form http://www.dmgh.de/SS_17/235 von außen verwendet werden können, die weitgehend selbsterklärend sind. Serverintern würden diese dann unter Verwendung der oben beschriebenen Methoden in den direkten Link in das Angebot der dMGH umgeschrieben (http://mdz1.bib-bvb.de/~db/bsb00000842/images/index.html?id=00000842&seite=247). Der Browser des Benutzers würde dann automatisch zur eigentlichen Zieladresse weitergeleitet. Der Vorteil einer derartigen Redirect-Engine liegt auf der Hand: Wer Links auf die dMGH setzen will, kann so einfache und nachvollziehbare URLs verwenden. Zusätzlich kann durch diese Abstraktionsschicht erreicht werden, dass Änderungen im Adressierungsschema der eigentlichen zugrundeliegenden dMGH-Webseite hier versteckt würden. Links auf Webseiten würden bei einem Wechsel der Bereitstellungssoftware nicht ihre Gültigkeit verlieren.
Bislang werden keine weiteren Dienste Angeboten. Geplant ist, dass hier später einmal beispielsweise Such-Plugins für Firefox-Browser angeboten werden können. Außerdem sollen auch Tutorials mit Beispielen für die praktische Anwendung der dMGH-Services angeboten werden. Falls in Zukunft Seiten von den MGH oder anderen geben wird, die auf diese API zurückgreifen, so sollen diese hier verlinkt werden.
Stand: 2006-02-22