RESTful API

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-https://ub-basel.atlassian.net/wiki/spaces/MD/pages/331939971 drei distinkte Konzepte:

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

Format

Als Query-Parameter

Als Request-Header

HTML

format=html (Standard)

Standard, kein Accept-Header notwendig

JSON-LD

format=json

Accept: application/json oder
Accept: application/ld+json

JSON Lines

format=jsonl

Accept: application/x-jsonlines

Beispiel:

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

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

1 curl -H 'Accept: application/ld+json' 'https://api.memobase.ch/record/aag-001-RBA1-4-15453_2

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

1 /<konzept>/search?q=<suchterm>

Nach dem Suchterm wird in allen indexierten Metadaten-Feldern gesucht.

Beispiel:

1 curl -H 'Accept: application/ld+json' 'https://api.memobase.ch/record/search?q=bern'

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:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { "@id": "api.memobase.ch/?q=*ern&format=JsonLd", "@type": "hydra:Collection", "@context": { "hydra": "http://www.w3.org/ns/hydra/core#" }, "hydra:member": [{...},{...},...], "hydra:totalItems": 46, "hydra:view": { "@id": "api.memobase.ch/?q=*ern&format=JsonLd&offset=20", "hydra:first": "api.memobase.ch/?q=*ern&format=JsonLd", "hydra:last": "api.memobase.ch/?q=*ern&format=JsonLd&offset=40", "hydra:limit": 10, "hydra:next": "api.memobase.ch/?q=*ern&format=JsonLd&offset=10", "hydra:next": "api.memobase.ch/?q=*ern&format=JsonLd&offset=30" } }
  • @id: Dereferenzierbare ID der Collection. Entspricht URL der Suche

  • @type: Ressourcentyp. Immer hydra:Collection

  • @context: Der JSON-LD-Kontext für das verwendete Objekt

  • hydra:member: Eine Liste mit den Metadaten-Objekte der Treffer

  • hydra:view.@id: Die ID der view, dem zurückgelieferten Ausschnitt aus allen Suchresultaten

  • hydra:first: Die ID der ersten view

  • hydra:last: Die ID der letzten view

  • hydra:limit: Die Anzahl der maximal in einer view zurückgegebenen Suchresultate

  • hydra: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:

1 curl -H 'Accept: application/ld+json' 'https://api.memobase.ch/record/search?q=bern&offset=100&size=20'

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:

1 curl -H 'Accept: application/x-jsonlines' 'https://api.memobase.ch/record/search?q=bern'

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:

1 curl -H 'Accept: application/ld-json' 'https://api.memobase.ch/record/search?q=bern&exists=abstract'

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

1 https://api.memobase.ch/record/advancedSearch?q=abstract:Lugano+AND+heldBy:mbcb:ati

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

1 https://api.memobase.ch/record/advancedSearch?q=abstract:Lugano+OR+heldBy:mbcb:ati

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

1 https://api.memobase.ch/record/advancedSearch?q=abstract:Lugano+AND+NOT+heldBy:mbcb:ati

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.

1 https://api.memobase.ch/record/advancedSearch?q=title:Lug*

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.

1 https://api.memobase.ch/record/advancedSearch?q=title:Tor~1

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.

Da die IDs der Objekte direkt in der URL gespeichert sind, deren Länge in der Regel auf 2048 Zeichen begrenzt ist, ist auch die Zahl der Objekte, die so gespeichert werden können, limitiert. Im Rahmen des verwendeten Kompressionalgorithmus liegt die Grenze bei ungefähr 330 Objekten.