Screenshot der OpenAPI-Beschreibung der API von musdb in Swagger UI

Die öffentliche Programmierschnittstelle der Ausgabe von museum-digital ist seit langem im Einsatz um beispielsweise Objekte direkt aus museum-digital auf den Webseiten der entsprechenden Museen auszuspielen. Die API ist stabil und etabliert.

In musdb, unserem Inventarisierungs- und Verwaltungstool, war und ist die Situation schwieriger. Einerseits ist musdb bezüglich seines Funktionsumfangs schlicht ungleich größer. Andererseits verunmöglichen die Reiter-basierte Struktur der Benutzeroberfläche und die bisher an vielen Stellen leider noch zu enge Kopplung zwischen Benutzeroberfläche und zugrundeliegender Abfragelogik ein API-Design wie in der Ausgabe, wo sich die API durch das einfache Anfügen von &output=json (bzw. ?output=json) aufrufen lässt. An vielen Stellen lässt sich zwar genau das tun, aber die Ergebnisse sind zwangsläufig unvollständig und von der Benutzeroberfläche gefärbt.

Andererseits ist eine API gerade für musdb interessant. Wenn Museen ihr lokales Inventarisierungsprogramm der Wahl verwenden könnten, und die Updates sofort auch in musdb und den öffentlichen Seiten gespiegelt würden, wäre das ein großer Fortschritt. Bisher bräuchte es dafür die Importfunktion, dass heißt, dass selbst bei einer vollen Automatisierung des Synchronisationsablaufs immer eine Verzögerung im Updatefluss bliebe.

Ein Anfang: Objekte per API updaten

Ein erster Schritt in Richtung einer dedizierten API für musdb, die unabhängig von der Benutzeroberfläche benutzt werden kann, ist nun getan. Zumindest Objektinformationen sind nun über eine gezielt dafür eingerichtete API auslesbar und bearbeitbar. Weitere Funktionen kommen sobald ein Bedarf besteht.

Und wenn man einmal damit anfängt, macht man es natürlich am besten gleich sauber. Mit der neuen API wurde ein Umformulieren und Neusortieren von vielen grundlegenden Funktionen auf technischer Ebene notwendig, die uns eine gute Gelegenheit gegebenen hat, gleich automatische Tests für alle in der API benutzten Funktionen zu schreiben. Ihre jetzt bestehenden Funktionen bleiben also sicher stabil.

Andererseits lag es nahe, die API beim Bauen gleich mithilfe eines Standards wie OpenAPI maschinenlesbar zu beschreiben. Gesagt, getan. Eine in JSON gefasste OpenAPI-Beschreibung der API von musdb findet sich in jeder regionalen Instanz unter /musdb/api, also etwa unter https://hessen.museum-digital.de/musdb/api.

Mit der Verwendung von OpenAPI eröffnen sich auch all die Tools, die allgemein für mit OpenAPI beschriebene Schnittstellen existieren. Eine vollständige menschenlesbare API-Dokumentation findet sich nun also im Handbuch (weil die API immer an die jeweilige regionale Instanz gebunden ist, funktioniert die Ausprobieren-Funktion im Handbuch nicht; eine gleich geformte API-Übersicht mit funktionierender Ausprobieren-Funktion ist in musdb in der Navigation verlinkt).

Nächste Schritte

Auch wenn sich jetzt alle Objektinformationen über die Schnittstelle bearbeiten lassen, ist die neue API von musdb noch sehr unvollständig. Ein nächster Schritt wird also definitiv die Erweiterung der API mindestens um die direkt anliegenden Funktionalitäten sein – z.B. das Auflisten der verfügbaren Sammlungen, sodass man überhaupt erst einmal die IDs zum Verlinken von Sammlungen ermitteln kann.

Auf der anderen Seite ist die API-Dokumentation mit OpenAPI ein großer Fortschritt auch gegenüber der Dokumentation der API der Ausgabe. Es bleibt zu hoffen, dass wir bald dazu kommen, auch für die API der Ausgabe eine OpenAPI-Beschreibung bereitzustellen. Geplant ist es auf jeden Fall.