Sie sind hier: dMGH > Services

Die digitalen Monumenta Germaniae Historica (dMGH)

Quelle: ralphbijker (cc-by)

dMGH-Services

Auf dieser Seite werden gebündelt Dienste zu den dMGH angeboten. Alle hier angebotenen Dienste befinden sich im Beta-Stadium. Bei Fragen wenden Sie sich bitte an Clemens Radl.

Inhalt

Einführung

Über das Hauptangebot der dMGH sind die Editionsbände der MGH zugänglich. 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 werden derartige Dienste gebündelt. Die Programmier-Schnittstelle (API), mit der die Dienste genutzt werden können, werden dokumentiert. Im folgenden werden im Abschnitt API-Definition allgemein die Funktionen vorgestellt, die die Schnittstelle zur Verfügung stellt. 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 dem Abschnitt REST-Schnittstelle wird 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.

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.

Kontakt: Clemens Radl <clemens.radl@mgh.de>.

API-Definition

get_API_version

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

resolve

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

get_img_num

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.

REST-Schnittstelle

Die Abfrage der Schnittstellen folgt dem REST-Prinzip. REST steht für Representational State Transfer. Hinweise zu den Prinzipien von REST finden sich in der in dem Artikel „Representational State Transfer“ in der Wikipedia.

get_API_version

URL: http://www.mgh.de/dmgh/services/rest?method=get_API_version
method:

resolve

URL: http://www.mgh.de/dmgh/services/rest?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.

method:
s:

get_img_num

URL: http://www.mgh.de/dmgh/services/rest?method=get_img_num&bsb=<BSB-Nummer>&page=<Seitennummer>
method:
bsb:
page:
URL: http://www.mgh.de/dmgh/services/rest?method=create_link&bsb=<BSB-Nummer>&img=<Bildnummer>
method:
bsb:
img: (optional)