Die Online-Abfrageschnittstelle für die ExpoDB

Die ExpoDB verfügt über eine Web-API, die Applikationen der Museen online mit Daten versorgt und aus ihnen online Daten übernimmt. Die Schnittstelle, über die Daten aus der ExpoDB zur Verfügung gestellt werden, beruht auf XML-Datensätzen, die aus imdas-pro-Datenbanken regelmäßig automati­siert nach Solr exportiert werden. Für die Abfrage der Daten aus der ExpoDB wird für diese Daten­sätze eine Reihe von Indexen aufbereitet, die eine Identifizierung sowie Selektieren und Sortieren er­möglichen. Zu festgelegten Attributen werden zusätzlich Indexlisten angelegt, die Facettierung bzw. Drill-Down der Suchergebnisse erlauben.

URL-Aufbau sowie universelle URL-Parameter und Basisformate

Die Online-Schnittstelle zur ExpoDB wird mit dem Protokoll https angesprochen. Es wird jeweils eine Testinstallation unter der Domain expotest.bsz-bw.de eingerichtet und, sobald die Grundkonfigura­tion in der Teststellung passt, eine Produktivinstallation unter expo.bsz-bw.de. Die Anwendungen, die die ExpoDB nutzen, sollen mit ihren produktiven Instanzen möglichst bald auf die Produktivinstal­lation unter expo.bsz-bw.de wechseln: Dies erlaubt auf der Testinstanz die Entwicklung der ExpoDB weiterzutreiben, wobei dort vorkomen kann, dass der Service aufgrund von Fehlern oder Wartungs­zeiten unterbrochen ist. Im Gegensatz dazu ist der Betrieb der Produktivinstanz stabiler, Wartungszeiten werden hier jeweils vorab angekündigt. Es wird empfohlen, auch für die Anwendungen, die die Schnittstelle nut­zen, jeweils eine Teststellung einzurichten, die auf expotest.bsz-bw.de konnektiert wird und es erlaubt, die Schnittstelle seitens der Bereitstellung und der Verwendung zu testen.

Für die folgenden Beispiele wird die Produktivinstallation expo.bsz-bw.de verwendet. Nach der Domänenangabe folgen die URL-Komponenten, die die anwendungsspezifische Installation der Schnittstelle bezeich­nen. Sie bestehen in der Regel aus einem dreistelligen Kürzel des Museums, z.B. sgs, smf, etc., sowie einer Bezeichnung der Teilsammlung bzw. intendierten Anwendung, z.B. sammlung-online oder digi­taler-katalog. Insgesamt ergibt sich bis dahin also z.B. https://expo.bsz-bw.de/sgs/digitaler-katalog. Dann folgen die Methoden der Schnittstellen /selekt, /image etc. und schließlich der durch „?“ abge­trennte Querystring. Die URL-Parameter werden im Querystring der URL als name=value-Paare ko­diert, die mit "&" getrennt sind und deren Reihenfolge nicht signifikant ist. Zur Darstellung von reser­vierten Zeichen (z.B. Leerzeichen) und Sonderzei­chen ist ein URL-Encoding der Parameterwerte er­forderlich.

Jede Installation ist mit einem Basis-Format konfiguriert, das ausgeliefert wird, sofern kein fmt-Parameter angegeben wird. Alternative Formate können mit dem URL-Parameter "fmt" angegeben werden. Welche zusätzlichen Formate für eine Schnittstelle eingerichtet und angeboten werden, wird für jede Installation verabredet und mitgeteilt.

Mit dem optionalen URL-Parameter "mim" oder dem http-Accept-Header, die "application/xml" oder "application/json" annehmen können, wird festgelegt, in welcher Syntax, XML bzw. JSON, das Ergeb­nis aufbereitet und mit welchem Mimetype es ausgeliefert wird. Vorgabewert ist "application/xml".

Mit einem URL-Parameter "dld" kann ein Dateiname übergeben werden, der bewirkt, dass Browser das Resultat zum Download unter diesem Dateinamen anbieten.

Die Schnittstelle kann Daten grundsätzlich in beliebigen Formaten ausliefern, DDB-LIDO, LEO-XML,…, die vorab definiert wurden und mit ihren spezifischen Strukturen, ggf. Namespaces und ggf. Meta­daten ausgestattet sind. In den Basisformaten der Schnittstelle werden die Ergebnisse bei Codierung als XML in ein result-Wurzelelement eingebettet, bei Codierung als JSON in ein JSON-Objekt. Danach folgen jeweils Header-Objekte, die für Einzeltreffer bzw. Trefferlisten unterschiedliche Angaben ent­halten. Die eigentlichen Treffer sind dann schließlich in ein records-XML-Element bzw. JSON-Array eingebettet.

Die XML- und den JSON-Codierungen der Basisformate gleichen sich strukturell, so dass umkehrbare Konvertierungen möglich sind: JSON-Namen werden im XML zu Element-Namen und umgekehrt. JSON-Objekte besitzen im XML ein Attribut „type=‘object‘“ und nur unterschiedlich benannte Kind­elemente; JSON-Arrays besitzen im XML ein Attribut „type=‘array‘“ und nur _-Kindelemente (also mit dem Unterstrich benannte). Andere XML-Attribute oder Namespaces werden nicht verwendet. Die Syntax des XML wird also dahingehend eingeschränkt, dass es strukturell äquivalent zu JSON ist.

Der Abruf von Einzeltreffern

Ein Einzeltreffer wird durch die URL-Komponente /selekt anhand eines obligatorischen id-Parameters abgerufen.

In den Basisformaten enthält der Header für Einzeltreffer nur eine „numfound“-Angabe, je nach Erfolg mit 1 oder 0, der angefragte id-Parameter sowie den fmt-Parameter.

Beispiel:

https://expo.bsz-bw.de/sgs/digitaler-katalog/selekt?id=000FDDCB46B9491EDA22F1BDDCB46B5B

{    
„head“ : {
          „numfound“ : „1“,
          „id“ : „000FDDCB46B9491EDA22F1BDDCB46B5B“,
           „fmt“ : „json“
      },
      „record“ : {
          „id“ : „000FDDCB46B9491EDA22F1BDDCB46B5B“,
           „sammlung“ : „Moderne Malerei“,
           „kuenstler“ : „Max Müller“,
           „titel“ : „Ein Bild“,
          „material“ : [ {„term“ : „Leinwand“}, {„term“ : „Karton“ } ],
           „technik“ : „Ölmalerei“,
           „entstehungsjahr“ : „2017“
      }
}

Der Abruf von Trefferlisten und Facetten

Für den Abruf von Trefferlisten erfolgt über die URL-Komponente /selekt. Ees sind folgende Para­meter vorgesehen, die alle optional sind. Sofern sie fehlen, werden sie mit Vorgabewerten belegt.

In den Basisformaten enthält der Header für Trefferlisten eine „numfound“-Angabe mit der Gesamt­anzahl der gefundenen Treffer, die angefragte Selektion (qry), die Sortierung (srt) und deren Richtung (ord), die Filterkriterien (flt), die Facettenfelder (fct), die Nummer des ersten Treffers (fst), die ange­forderte Anzahl von Treffern (len, die Anzahl der gelieferten Datensätze kann kleiner sein) sowie das Format (fmt) angegeben. Soweit ein Parameter nicht übergeben wurde, wird der Vorgabewert bzw. null verwendet. Gibt es keine Treffer, wird im Header die Trefferanzahl 0 angegeben und das „records“-Element ist leer.

An das Ende der Trefferliste wird eine Abschnitt facets angefügt, der zu jeder gewählten Facette die durch lmt begrenzte Anzahl von Indexbegriffen angibt. Die Indexbegriffe werden zusammen mit der Anzahl ihres Vorkommens angeben und entsprechend dem Parameter fcs sortiert. 

Beispiel:

https://expo.bsz-bw.de/sgs/digitaler-katalog/export?qry=person+any+"müller"&fst=20&flt=technik:Öl&fct=material,jahr

<?xml version='1.0' encoding='utf-8'?>
<result>
      <head>
           <numFound>3</ numFound>
           <qry>person any “müller”</ qry >
           <srt>relevance</srt>
           <ord>asc</ord>
           <fst>20</fst>
           <len>10</len>
           <fct>material,jahr</fct>
           <flt>technik:Öl</flt>
           <fmt>xml</fmt>
      </head>
      <records>
           <record>
                 <imdasid>000FDDCB46B9491EDA22F1BDDCB46B5B</imdasid>
                 <title>Max Müller: Ein Bild<title>
           </record>
           <record>
                 <imdasid>000FDDCB46B9491EDA22F1BBFD2F435B</imdasid>
                 <title>Max Müller: Noch ein Bild<title>
           </record>
           <record>
                 <imdasid>000FDDCB46B9491EAFDDCB4BFD2F435B</imdasid>
                 <title>Sabine Müller: Auch ein Bild<title>
           </record>
      </records>
      <facets>
            <material>
                 <term>Leinwand</term><anzahl>234</anzahl>
                 <term>Karton </term><anzahl>84</anzahl>
           </material>
           <zeit>
                 <term>1845</term><anzahl>2</anzahl>
                 <term>1846 </term><anzahl>18</anzahl>
                       …
                 <term>2016</term><anzahl>3</anzahl>
           </zeit>
      </facets>
</result>

Eine Anfragesprache für die ExpoDB

Zur Formulierung des Selektionskriteriums im qry-Parameter wird eine Syntax festgelegt. Die abzu­fragende Datenbasis wird als Text oder Zahlen betrachtet und basiert auf den Indexen der ExpoDB. Suchterme können mit * als Wildcard links- und rechtstrunkiert und als Phrase formuliert werden, Listen von Suchtermen können konjunktiv oder disjunktiv zu Indexen relationiert sein, einzelne Such­terme können auch mit kleinergleich, größergleich oder gleich relationiert werden. Suchklauseln aus Index und Suchtermen können über boole‘schen Operatoren verknüpft werden, wobei die Auswer­tung von links nach rechts erfolgt, soweit nicht Klammern eine andere Reihenfolge festlegen.

Indexe

Die Indexe sind vorab als eindeutige kurze Bezeichnungen, z.B. nummer, person, material, verein­bart; die Bezeichnung text_de ist für den Index über alle suchbaren Textinhalte in deutscher Sprache reserviert.

Suchterme

Suchterme sind einzelne Worte, Bronze, Eisen, die durch Leerzeichen getrennt zu Listen zusammen­gefasst werden, die durch Anführungszeichen begrenzt sind: "Bronze Eisen“. Dem Wort kann ein * vor- oder nachgestellt werden, was eine Links- bzw. Rechtstrunkierung bedeutet, z.B. Eisen* sucht nach Eisen, Eisennagel und Eisenbahn. Groß- und Kleinschreibung ist bei Suchtermen nicht signifi­kant, d.h. Eisen und eisen sind semantisch identisch.

Relationen und Suchklauseln

Indexbezeichnern und Suchtermen bzw. Suchtermlisten werden mit den Relationen any, all und adj zu Suchklauseln gruppiert. Die Semantik von any ist dabei, dass der Suchterm bzw. wenigstens ein Term aus einer Suchtermliste im Index enthalten ist: Die Suchklausel material any "Eisen Bronze“ selektiert also alle Datensätze, für die im Material-Index entweder Eisen oder Bronze oder Eisen und Bronze enthalten ist; die Suchklausel material any "Gold“ erfordert, dass im Material-Index Gold ver­zeichnet ist.

Die Semantik von all ist, dass der Suchterm bzw. alle Terme aus einer Suchtermliste im Index enthal­ten ist: Die Suchklausel material all "Eisen Bronze" selektiert also die Datensätze, für die im Material-Index sowohl Eisen als auch Bronze enthalten sind.

Die Semantik von adj ist, dass der Suchterm bzw. die Suchtermliste in ihrer Reihenfolge als Phrase im Index enthalten ist: Die Suchklausel person adj "Hans Meier" selektiert also die Datensätze, für die im Personen-Index die Wörter Hans Meier unmittelbar aufeinanderfolgend enthalten ist; die Such­klausel material adj "Gold" erfordert, dass im Material-Index Gold verzeichnet ist.

Gibt es nur einen Suchterm sind die Relationen any, all und adj semantisch identisch. Für die Rela­tionen eq, le, ge wird immer nur der erste Suchterm in einer Liste berücksichtigt; typischerweise sollte dieser eine (Jahres-)zahl sein.

Die Semantik von eq, le bzw. ge ist dann, dass der Suchterm gleich, kleiner gleich bzw. größer gleich als ein Term im Index ist: Die Suchklausel jahr le 1984 selektiert also alle Datensätze zu Jahren kleiner als oder gleich 1984, die Suchklausel jahr eq 1985 Datensätze, die als (Herstellungs)jahr 1985 aufweisen.

Boolsche Verknüpfungen

Suchklauseln können über bool’sche Operatoren and, or und not zu größeren Abfragen kombiniert werden. Der Operator and bedeutet dabei, dass sowohl die Suchklauseln links als auch die Such­klausel rechts vom Operator erfüllt sein müssen: material any "Eisen" and nummer all "4 7b" selektiert also die Datensätze, die im Material-Index Eisen aufweisen und im Nummern-Index die Eintrage 4 sowie 7b.

Der Operator or bedeutet, dass die linke Suchklausel erfüllt ist, oder die rechte Suchklausel oder beide. Enthält der Nummern-Index also den Eintrag 7b, wäre demnach der Ausdruck material any "Eisen" or nummer any "4 7b" erfüllt.

Der Operator not bedeutet, dass die linke Suchklausel erfüllt sein muss, die rechte aber nicht erfüllt sein darf – logisch also ein „and not“: material any "Eisen" not nummer all "4 7b" bedeutet dem­nach, dass der Material-Index Eisen enthalten muss, der Nummern-Index aber weder 4 noch 7b ent­halten darf.

Werden mit and, or oder not mehr als zwei Suchklauseln kombiniert, so werden zunächst die beiden linken Suchklausel ausgewertet und kombiniert, dann das Ergebnis mit der dritten Klausel u.s.w.: material all "gold" and "nummer" any 9 or jahr le 1984 not nummer all "4 7b" selektiert also die Datensätze, für die der Material-Index Gold enthält sowie der Nummern-Index 9, oder aber deren Jahr-Index Werte kleiner oder gleich 1984 enthält; jedenfalls darf aber der Nummern-Index nicht (gleichzeitig) 4 und 7b enthalten.

Es sind auch Klammern zur Variation der Auswertungsreihenfolge bei drei und mehr Suchklauseln vorgesehen: In material all "gold" and ("nummer" any 9 or jahr le 1984) not nummer all "4 7b" selektiert nun alle Treffer, für die als Material Gold angegeben ist und entweder eine Nummer 9 oder das Jahr kleiner 1984 ist. Reduziert wird das Ergebnis um alle Treffer, deren Nummern sowohl 4 als auch 7b sind.

Weitere Beispiele

material any "Eisen Bronze" not material all "Gold Messing" or nummer any 4
Material ist Eisen oder Bronze, aber Material ist weder Gold noch Messing oder die Nummer ist 4.

text any "Eisen Meier" and material all "Messing*" not nummer any "4 7"
Irgendwo im Datensatz kommt Eisen und / oder Meier vor und ein Material beginnt mit Messing, aber die Nummer ist weder 4 noch 7.

material all Holz Eisen not nummer any 4 or person all "Meier Müller-Schmidt"
Der Materialien-Index enthält sowohl Holz als auch Eisen, jedoch der Nummern-Index nicht die 4 oder aber, unabhängig vom vorigen, enthält der Personen-Index sowohl Meier als auch Müller-Schmidt.

Bemerkung: Da Inventarnummern oft aus recht kurzen Komponenten zusammengesetzt sind, sollten sie mit adj gesucht werden, da Solr kurze Textbestandteile beim Suchen ignoriert.

Abruf von Medien für die die ExpoDB

In der ExpoDB sind insbesondere auch Pfade zu Bildern und anderen Mediendateien abgelegt.

Mittlerweile verwalten viele Museen ihre Bilder und anderen Assets in der Medienbe­reitstellung von MusIS oder in externen Asset-Management-Systemen. Bilder und Dokumente, die so verwaltet werden, werden in der Schnittstelle mit ihrer Abruf-URL ausgegeben. Die nutzende Anwen­dung muss diese URLs, z.B. falls sie eine IIIF-Schnittstelle adressieren, mit den für den Bereitstellungs­service möglichen Parametern konfigurieren.

Soweit die Pfade auf das sog. "Z-Laufwerk" des BSZ führen, adressieren sie kleingerechnete Arbeitsderivate der Museen in imdas pro. Diese Pfade werden  nicht in den Trefferformaten ausgegeben und können nicht direkt zum Abruf dieser Ressourcen über das Web verwendet werden. Vielmehr erfolgt der Abruf von Bildern sowie anderen Mediendateien über einen https-GET-Methode /image, /audio bzw. /pdf in dem die imdasid des Datensatzes, optional die Nummer des Bildes, des Audiofiles bzw. pdfs in der Liste der zum Datensatz publizierten Bilder sowie optional die Bilddimension als Parameter angege­ben sind. Folgende Parameter sind dabei vorgesehen:

Bilder werden im JPG-Format unter dem Mimetype „image/jpeg“ ausgeliefert, Audio-Dateien unter dem Mimetype „audio/mpeg“ sowie PDF-Dateien unter dem Mimetype „application/pdf“.

Beispiel:

https://expo.bsz-bw.de/sgs/digitaler-katalog/image?id=000FDDCB46B9491EDA22F1BDDCB46B5B &width=200&mode=h

https://expo.bsz-bw.de/sgs/digitaler-katalog/01/pdf?id=000FDDCB46B9491EDA22F1BDDCB46B5B &pos=2
https://expo.bsz-bw.de/sgs/digitaler-katalog/01/audio?id=000FDDCB46B9491EDA22F1BDDCB46B 5B

Fehlermeldungen

Falls eine Parametrisierung fehlerhaft ist, also falsch strukturiert ist, nicht vereinbarte Index-Bezeich­ner verwendet, ein qry-Parameter entspricht nicht der Syntax der Anfragesprache, beim Abruf von Medien wird eine id angegeben, zu dem kein Datensatz existiert, oder ein img-Parameter, zu dem es kein Bild mit der angegebenen Nummer gibt, wird der Fehlercode http-400 zurückgeliefert.

Sofern ein anderer serverseitiger Fehler auftritt, wird der Fehlercode http-500 zurückgeliefert.

Bemerkung: Manche Installationen sind mit einer sog. „Viewer“-Anwendung ausgestattet, die mittels Angular implementiert wurde. In diesem Fall werden http-Fehler für interne Angular-Zwecke anders verwendet.

CORS

Zum Zugriff aus JavaScript-Anwendungen können CORS-Filter definiert werden, die bezogen auf einzelne Abfragemethoden ggf. für einzelne IPs die Zugriffsbeschränkung entsprechend der Same-Origin-Policy aufheben