API und REST-Schnittstelle für eigene Programmierung

API-Definition und REST-Schnittstelle können bei der Arbeit mit den dMGH unterstützen, z.B. hinsichtlich:

• Abkürzungsauflösung
• direkte Verlinkung unter Angabe des Bandes und der Seitenzahl
• Zitierung von Urkundeneditionen nach Herrschernamen und Urkundennummer

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.

create_link

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 ¶

resolve ¶

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.

get_img_num ¶

create_link ¶