RESTful API
- Sebastian Schüpbach
Die RESTful API von Memobase ist eine Schnittstelle zu den Metadaten von auf http://memobase.ch verfügbaren Dokumenten, Beständen und Institutionen. Die primäre Intention der Schnittstelle ist die Möglichkeit zur automatisierten Abfrage von Metadaten zwecks Weiternutzung bzw. -verarbeitung auf einem externen System. Darüber hinaus bietet die Schnittstelle aber auch ein einfaches User Interface für die Suche nach und Anzeige der verfügbaren Metadaten.
Verfügbare Konzepte
Die Schnittstelle umfasst basierend auf dem Memobase-Datenmodell drei distinkte Konzepte:
record: Ein Objekt, bspw. https://api.memobase.ch/record/aag-001-RBA1-4-11620_1recordSet: Ein Bestand, bspw. https://api.memobase.ch/recordSet/aag-001institution: Eine Institution, bspw. https://api.memobase.ch/institution/aag
Eine Suche ist nur innerhalb eines Konzeptes möglich.
Vorhandene Felder
Die in einem Konzept vorhandenen Felder lassen sich über den jeweiligen properties-Endpunkt anzeigen:
Maschinelle Abfrage
Eine kompakte Übersicht der verfügbaren Endpunkte bietet die Swagger UI.
In den folgenden Abfragebeispiele wird das weitverbreitete und quelloffene Kommandozeilenwerkzeug cURL genutzt. Selbstverständlcih kann ein beliebiges anderes Programm genutzt werden, mit dem HTTP-Abfragen gemacht werden können.
Datenformate
Die Metadaten zu einzelnen Objekten (Dokumente, Bestände und Institutionen) stehen neben der HTLM-Repräsentation im Linked Data-Format JSON-LD zur Verfügung. Zum Download von Dumps, bspw. der Ergebnisliste einer Suche, können JSON-LD-Objekte als JSON Lines ausgegeben werden, wo ein Objekt jeweils in einer Zeile ausgegeben wird.
Die Angabe des gewünschten Formates erfolgt entweder über das Accept-Feld des HTTP-Request-Header oder im Query-Parameter format.
Format | Als Query-Parameter | Als Request-Header |
|---|---|---|
HTML |
| Standard, kein |
JSON-LD |
|
|
JSON Lines |
|
|
Beispiel:
curl -H 'Accept: application/ld+json' 'https://api.memobase.ch/record/aag-001-RBA1-4-11620_1'
Um eine JSON-LD-Repräsentation eines einzelnen Dokuments zu erhalten, ist es alternativ möglich, der Dokumenten-ID das Suffix .json hinzuzufügen. Beispiel:
curl 'https://api.memobase.ch/record/aag-001-RBA1-4-11620_1.json'Abfrage von einzelnen Dokumenten
Einzelne Dokumente werden über das zugehörige Konzept und die spezifsiche ID abgefragt.
Beispiel:
curl -H 'Accept: application/ld+json' 'https://api.memobase.ch/record/aag-001-RBA1-4-15453_2Einfache Suche
Einfache Suchen laufen über den /search-Endpunkt. Werden Suchen ohne einen Query-Teil ausgelöst, werden alle Dokumente eines Dokumentes zurückgegeben (Match all query).
Für einfache Suchen mit einem Suchterm lautet die Syntax:
Nach dem Suchterm wird in allen indexierten Metadaten-Feldern gesucht.
Beispiel:
Dies führt eine Suche nach ‘Bern’ in allen Metadaten-Feldern von Memobase-Objekten durch und liefert die Metadaten der ersten zehn Treffer als JSON-LD-Objekte zurück.
Suchbegriffe werden mit AND verknüpft, d.h., alle Begriffe müssen in den indexierten Feldern vorkommen. Treffer im Titel und im Abstract werden höher gewichtet. Die Sortierung der Suchresultate erfolgt nach Relevanz. So werden Dokumente, die die Suchbegriffe im Titel tragen, früher gelistet als solche, in denen die Begriffe in anderen Feldern gefunden werden konnten.
Hydra
Wird wie im obigen Beispiel eine JSON-LD-Repräsentation der Suchtreffer angefordert, werden die Resultate als sogenannte Hydra-Collection zurückgeliefert. Sie ist Teil des Hydra-Vokabular, das eine Standardisierung der Kommunikation zwischen Web APIs und Clients zum Ziel hat. Eine Collection enthält folgende Felder:
@id: Dereferenzierbare ID der Collection. Entspricht URL der Suche@type: Ressourcentyp. Immerhydra:Collection@context: Der JSON-LD-Kontext für das verwendete Objekthydra:member: Eine Liste mit den Metadaten-Objekte der Trefferhydra:view.@id: Die ID der view, dem zurückgelieferten Ausschnitt aus allen Suchresultatenhydra:first: Die ID der ersten viewhydra:last: Die ID der letzten viewhydra:limit: Die Anzahl der maximal in einer view zurückgegebenen Suchresultatehydra:previous: Die vorangehende view (falls vorhanden)hydra:next: Die nächste view (falls vorhanden)
Scrolling
Mittels der Query-Parameter offset und size kann ein bestimmter Ausschnitt aus den gesamten Suchresultaten angefragt werden.
Beispiel:
Hier werden 20 Suchresultate ab Suchresultat 100 zurückgegeben.
Suchresultate über das Offset 10’000 werden ignoriert.
Es ist aber möglich, die Daten als Dump herunterzuladen. Dazu muss als Datenformat JSON Lines gewählt werden.
Beispiel:
Werden JSON Lines angefordert, werden immer alle Suchresultate zurückgegeben, unabhängig von allfällig vorhandenen offset- und size-Parametern!
Weiteres Filtern von Suchresultaten
Mittels des exists-Parameters können Dokumente herausgefiltert werden, deren Metadaten ein bestimmtes Feld beinhalten.
Beispiel:
Hier werden nur Objekte zurückgegeben, welche über das abstract-Feld verfügen. Eine Übersicht über die vorhandenen Felder in einem Konzept gibt der jeweilige properties-Endpunkt.
Fortgeschrittene Suche
Die fortgeschrittene Suche wird über den /advancedSearch-Endpunkt aufgerufen. In diesem Suchmodus unterstützt die Suche alle Funktionalitäten, welche die Elasticsearch Query String Syntax bietet.
Beispiel 1: AND-Verknüpfung
Hier werden Objekte gesucht, welche in der Beschreibung das Wort ‘Lugano’ enthalten und zur Institution ‘ati' (Archivio di Stato del Cantone Ticino) gehören.
Beispiel 2: OR-Verknüpfung
Es werden Objekte zurückgegeben, welche entweder in der Beschreibung das Wort ‘Lugano’ enthalten oder zur Institution ‘ati' (Archivio di Stato del Cantone Ticino) gehören.
Beispiel 3: NOT-Bedingung
Angezeigt werden Objekte, welche in der Beschreibung das Wort ‘Lugano’, aber nicht dem Archivio di Stato del Cantone Ticino gehören.
Beispiel 4: Wildcards, Regex
Mittels Wildcards können Begriffe gesucht werden, wo einzelne (?) oder 0-n aufeinanderfolgende Zeichen (*) beliebig sein können.
Hier werden Treffer zurückgegeben, welche das Wort ‘Lugano’, aber bspw. auch ‘Lugli' oder ‘lugam’ enthalten.
Durch reguläre Ausdrücke können noch weitergehende Suchmuster gebildet werden. S. die Elasticsearch-Dokumentation für eine ausführliche Beschreibung.
Beispiel 5: Fuzziness
Mit dem Fuzzy-Operator ~ werden Begriffe gesucht, die ähnlich wie der Suchbegriff sind. Es wird dafür die sogenannte Damerau-Levenshstein-Distanz verwendet, welche besagt, in wie vielen Ersetzungsschritten (Entfernen, Hinzufügen oder Ersetzen von einzelnen Zeichen sowie dem Vertauschen von zwei benachbarten Zeichen) von einem zum anderen Begriff gelangt werden kann.
Die Anzahl der Schritte ist standardmässig zwei, das kann aber angepasst werden.
Bei dieser Suche ergeben sich Treffer, die ‘Tor’, aber bspw. auch ‘Tür’, ‘For’, ‘Tour’ oder ‘Ton’ enthalten.
Im Übrigen ist die fortgeschrittene Suche analog zur einfachen Suche.
Bedienungsanleitung User Interface
Konzeptauswahl
Die Auswahl des Konzeptes erfolgt über die Buttons Record, RecordSet und Institution. Standardmässig ist Record ausgewählt.
Einfache Suche
Die einfache Suche erfolgt über die Selektion des Suchmodus “Basic Search” (standardmässig ausgewählt) unterhalb der Konzeptauswahl. Im Suchschlitz können eine oder mehrere Suchbegriffe eingegeben werden, wobei die Suche immer über alle Metadaten-Felder ausgeführt wird. Eine Suche nach vorhandenen Feldern ist im UI direkt nicht möglich.
Fortgeschrittene Suche
Die fortgeschrittene Suche erfolgt über die Selektion des Suchmodus “Advanced Search) unterhalb der Konzeptauswahl. Im Dropdownmenü wird das Feld ausgewählt, in dem gesucht werden soll. Standardmässig erfolgt eine Suche über alle Felder. Im Suchfeld in der Mitte des Formulars wird der Suchterm eingegeben. Unterstützt werden im Unterschied zur einfachen Suche alle Funktionalitäten der Elasticsearch Query String Syntax.
Weitere Felder werden mithilfe des “+”-Buttons rechts hinzugefügt und mit dem “-”-Button entfernt. Mit dem Dropdownmenü links davon wird die Verknüpfung (AND/OR) zwischen den verschiedenen Suchfeldern definiert.
Anzeige der Suchresultate
Die Suchresultate werden unterhalb der Suche eingeblendet. Auf der Startseite werden die ersten zehn Treffer der Leersuche über das Record-Konzept angezeigt. Damit die Leersuche eine konsistente Sortierung zeitigt, werden die Resultate nach ihrem Identifier in aufsteigender Reihenfolge geordnet (in allen anderen Fällen werden die Suchresultate nach ihrer Relevanz gelistet).
Die Navigation über die Suchresultate erfolgt via dem Navigationsmenü links oberhalb der Trefferliste.
Rechts davon lassen sich die Zahl der angzeigten Resultate anpassen (10, 20, 50, 100). Über den Button ganz rechts kann das ganze Resultateset als Dump heruntergeladen werden.
Durch Klick auf die einzelnen Treffer wird auf deren Objektseite navigiert. Das Icon zeigt den jeweiligen Typ des Objektes an (wird nur bei Suche in Objekten angezeigt).
Um ein Objekt in eine Kollektion aufzunehmen (oder es aus dieser zu entfernen), muss die Checkbox links davon aktiviert (deaktiviert) werden. Diese Option steht nur für Bestände und Institutionen nicht zur Verfügung.
Objektseite
Auf der Objektseite werden die Details eines Objektes (eines Bestandes, einer Institution) angezeigt.
Im grauen Kasten oben finden sich die wichtigsten Angaben zum Objekt sowie die Links zu den jeweiligen Eltern- bzw. Kindelementen (Objekt, Bestand, Institution).
Durch die Buttons ganz oben kann das Dokument auf http://memobase.ch aufgerufen werden (“Show on Memobase”), als JSON-LD-Objekt angezeigt werden (“Show as JSON-LD Object”) oder einer Kollektion hinzugefügt (“Add to basket”) bzw. aus dieser entfernt werden (“Remove from basket”).
Ist ein Thumbnail für das Objekte vorhanden, wird dieses ebenfalls im grauen Kasten angezeigt. Mit einem Klick auf das Bild wird dieses im Vollformat eingeblendet.
Unterhalb des grauen Kastens werden alle Felder des Dokumentes angezeigt. Um die Übersicht zu wahren, wird anfänglich nur die oberste Feldebene eingeblendet. Um die darunterliegende Ebene anzuzeigen, muss auf das ▸-Symbol geklickt werden. Das Einklappen von ausgeklappten Elementen erfolgt analog mit einem Klick auf das ▾-Symbol.
Die Anzeige unterscheidet sich in Details zwischen Detailseiten für Objekte, Bestände und Institutionen.
Objektkollektion
Sobald ein erstes Objekt einer Kollektion hinzugefügt worden ist (dies kann in der Suchresultate-Anzeige für Objekte oder in der Objektansicht erfolgen), erscheint in der Konzeptauswahl ein neuer Button, “Basket”. Wird auf ihn geklickt, wird die Objektkollektionsansicht geöffnet. Sie entspricht grundsätzlich der Suchresultate-Anzeige, verfügt aber zusätzlich über den Button “Copy basket link”. Durch einen Klick auf diesen wird die URL der Kollektion kopiert. Da in ihr die IDs der anzuzeigenden Objekte enkodiert sind, lässt sich so die Kollektion “speichern” oder mit weiteren Personen teilen.