Bericht zum Workshop „APIs for text-based digital editions“ am 25.09.2025

0 Veröffentlicht von Katharina Brückmann am

Wird es sie bald geben, die eine API, sie alle zu finden und auf ewig zu binden? Im Workshop „APIs for text-based digital editions“, der in Kooperation der Universitätsbibliothek Heidelberg und Text+ am 25.09.2025 online stattfand, wurde unter anderem auch das diskutiert. Mehr Informationen dazu gibt es im folgenden Beitrag, der den Workshop und dessen zentrale Ergebnisse zusammenfasst.

Einleitung

Was sind APIs?​

Programmierschnittstellen („API“ von Application Programming Interface) stellen Funktionen bereit, mit denen Informationen aus einem System abgerufen oder gesendet werden können. Da die zulässigen Abfragen, möglichen Parameter und Rückgaben einer API genau definiert sind, können verschiedene Systeme und Anwendungen so einheitlich und effizient auf die Daten zugreifen, ohne die genaue Struktur des zugrundeliegenden Systems kennen zu müssen. 

Beispielsweise bietet das Hochschulbibliothekszentrum des Landes NRW die API lobid-gnd an, durch die der Zugriff auf die Bestände der Gemeinsamen Normdatei (GND) der Deutschen Nationalbibliothek verhältnismäßig aufwandsarm in andere Anwendungen integriert werden kann. In dem Webportal einer digitalen Edition könnten zum Beispiel weitere Informationen zu einer Named Entity angezeigt werden, indem beim Klick auf diese im Hintergrund eine Anfrage an einen Endpunkt der lobid-gnd-API gesendet wird (z.B.: https://lobid.org/gnd/search?q=Heidelberg&format=json). Diese liefert die in der GND gespeicherten Informationen in einem einheitlichen – und in der Dokumentation der API beschriebenen – Format aus, das so seitens des Webportals für die Anzeige aufbereitet werden kann und die gewünschte Information angezeigt wird (z.B.: „Heidelberg – Stadt am Neckar, Regierungsbezirk Karlsruhe, 1196 urkundl. erwähnt“).

Die Zugänglichmachung der Datenschicht einer Edition über eine API kann damit die Recherche, Vernetzung und Nachnutzung der Editionsdaten bedeutend erleichtern; sie trägt also auch zur Umsetzung der FAIR-Prinzipien bei. Nicht ohne Grund fragt der Kriterienkatalog der Rezensionszeitschrift für digitale Editionen RIDE explizit nach dem Vorhandensein von technischen Schnittstellen.1

Idee eines Workshops zum Thema APIs

APIs finden jedoch trotz der vielen Möglichkeiten, die sie mit sich bringen, bisher noch keine breite Anwendung im Bereich der digitalen Editionen und der auf ihnen aufbauenden Forschung. Deshalb wurde in Kooperation der Universitätsbibliothek Heidelberg mit Text+ ein gemeinsamer Workshop zum Thema „APIs for text-based digital editions“ veranstaltet.

Ziel des Workshops war es, mögliche API-Nutzer:innen (z.B. Editionswissenschaftler:innen, Digital Humanists, Sprachwissenschaftler:innen) mit den Dienstanbieter:innen und Entwickler:innen zusammenzubringen, um gemeinsam Grenzen und Möglichkeiten der Schnittstellen zu erkunden, Bedarfe, Wünsche und Weiterentwicklungsmöglichkeiten zu sammeln sowie eventuelle Hürden bei der Verwendung und Implementierung zu minimieren.

Der Workshop

Teilnehmer:innen

Am 25.09. trafen über 60 Personen für den Online-Workshop zusammen. Neben Forscher:innen aus Deutschland, Österreich und der Schweiz waren auch Teilnehmende aus u.a. Polen, der Türkei, Italien und den USA dabei, womit sich die Entscheidung, Englisch als Workshop-Sprache zu verwenden, direkt als richtig erwies. Vertreten waren u.a. Bibliotheken, Forschungsinstitute, dedizierte DH-Zentren und Data Science Labs sowie auch konkrete Forschungsprojekte.

Programm

Das etwa sechsstündige Programm gliederte sich dabei in drei Teile:

  • Vortragsteil: Vier Präsentationen à 20 Minuten zu konkreten Schnittstellen(-spezifikationen) mit jeweils unmittelbar anschließender, kurzer Fragerunde
  • Diskussionsteil: Zwei Breakouträume (einmal mit technischem Fokus und einmal mit Fokus auf Nutzung und Bereitstellung) mit anschließender gemeinsamer Zusammenfassung
  • Anwendungsteil: Vortrag zur Implementierung der DTS-Spezifikation im TEI Publisher als praktisches Beispiel für die Schnittstellenintegration; ebenfalls mit anschließender Diskussionsrunde.

Vorgestellte APIs

Die vier vorgestellten Schnittstellen(-spezifikationen) werden nachfolgend zum besseren Überblick kurz erläutert.

Distributed Text Services

Diese API-Spezifikation wird seit 2015 unter ständigem Input der Community gemeinschaftlich entwickelt und liegt aktuell als Release Candidate vor; die Veröffentlichung von Version 1.0 soll dieses Jahr erfolgen. Die Spezifikation sieht neben dem Einstiegspunkt drei Endpunkte (d.h. Orte, an die Anfragen gesendet werden können) vor:

Citable units können dabei grundsätzlich jeder Art sein; denkbar wären z.B. Kapitel, Paragraphen, Seiten oder auch Verszeilen. Durch einen oder mehrere sogenannte citationTrees wird für jede Ressource hinterlegt, welche Strukturen für sie als mögliche Zugriffsform bereitstehen, sodass beispielsweise vom selben Text (sofern implementiert) sowohl die ersten 20 Seiten als auch semantisch-logische Einheiten wie z.B. 3 Kapitel abgerufen werden könnten. Das primäre Format, das über den document-Endpoint bereitgestellt wird, ist TEI-XML; über den mediaType-Parameter können jedoch auch andere verfügbare Serialisierungen der Daten abgerufen werden, z.B. plain text, HTML oder ganz andere. Die übrigen DTS-Endpunkte nutzen JSON-LD zur Auslieferung der Informationen.

SHINE API

Die SHINE API-Spezifikation wurde im Kontext des RISE-Projektes vom Max-Planck-Institut für Wissenschaftsgeschichte in Berlin sowie der Staatsbibliothek zu Berlin entwickelt und liegt in Version 1 vor. Ähnlich wie bei DTS werden Texte hier als Hierarchie von content units und sections verstanden, die in resources enthalten sind, wobei die Ressourcen wiederum in collections gesammelt werden. Über insgesamt 7 Endpunkte ist dabei u.a. Folgendes möglich, wobei die Antwort stets im JSON-Format erfolgt:

  • collections, resources, sections und content units sowie deren zugehörige Metadaten  einsehen
  • eigene Korpora aus resources zusammenstellen und diese abrufen
  • verfügbare Forschungswerkzeuge für collections abrufen/hinterlegen

Zum letzten Punkt: Ressourcen, die über eine SHINE API zugreifbar sind, können die RISE-Infrastruktur nachnutzen; darunter den Import in Textanalyse- oder Annotationsplattformen wie MARKUS und Recogito oder die Einbindung in den RISE Catalog. Über die RISE-Middleware kann zudem beim Zugriff auf ausgewählte Ressourcen ein Authentifizierungsschritt ergänzt werden, wenn gewünscht.

UDT-ITF API

Dieser API-Spezifikationsvorschlag orientiert sich am IIIF-Standard und wurde in dem 2-Jahres-Projekt „Unlocking Digital Texts: Towards an Interoperable Text Framework“ erarbeitet. Er liegt aktuell in Version 0.1.0-beta vor und wird weiter ausgebaut. 

Der Zugriff auf Textfragmente erfolgt hier mittels der Text Fragment API, während die Text Information API Metadaten zu den Textressourcen und eventuellen Versionen ausliefert. Anders als die bisher vorgestellten API-Spezifikationen ist die Versionierung damit explizit in der Spezifikation enthalten – während bei DTS z.B. indirekt mittels Dublin Core-Metadateneinträgen angegeben werden könnte, dass eine Ressource eine andere ersetzt, ist die Version hier Teil der Fragment-Anfrage: http://{server}{/prefix}/{identifier}/{version}/{mode}/{fragment}/{quality}{.format}

Die Fragmente werden dabei durch sogenannte modes spezifiziert. Vordefiniert sind u.a. char, token und book – bei char würden Fragmente z.B. anhand von character offsets zugreifbar sein, während book eine weitere Untergliederung in Seiten, Zeilen und Zeichen zulässt, sodass book-Fragmente mittels Koordinaten aus Seite–Zeile–Zeichen gebildet werden können. Diese Fragmente werden stets anhand der plaintext-Version einer Ressource berechnet, d.h. ein Server, der diese API-Spezifikation implementiert, muss sicherstellen, dass eventuelles Tagging ignoriert wird. Weitere, selbst definierte modes auf Basis der vordefinierten Möglichkeiten sind ebenso zulässig wie das Zugreifen auf die gesamte Textressource mittels der mode “full”. Als auslieferbare Formate sind dabei txt, TEI-XML, HTML und Markdown im Entwurf vorgesehen. 

Auf die weitere Gliederung der Textressourcen in übergreifende Sammlungen wird hier verzichtet, d.h. das Konzept der collections gibt es hier nicht.

TextAPI

Die TextAPI-Spezifikation ist ebenfalls von IIIF inspiriert und wird von der SUB Göttingen entwickelt. Die Spezifikation liegt in Version 1.4.2 vor, wobei das Release der Version 2.0.0 aktuell in Planung ist. 

Mittels der TextAPI können collections, manifests (physische Expression eines Werks) sowie items oder jeweils zugehörige Metadaten abgerufen, erstellt, gelöscht und ersetzt werden. Im JSON-Inhaltsobjekt können beliebige Serialisierungen der Ressourcen per URL verlinkt werden; worum genau es sich bei einem item handelt, wird dabei durch den Typ-Eintrag im JSON-Objekt klar, der frei gewählt werden kann. Ebenfalls enthalten ist dort auch ein data integrity object, in welchem die Prüfsumme der referenzierten Ressource sowie der zur Generierung verwendete Algorithmus hinterlegt werden. Diese Möglichkeit zur Sicherstellung der Datenintegrität ist in den anderen Spezifikationen nicht integriert oder zumindest nicht pflichtmäßig enthalten.

Das hier entwickelte Ökosystem umfasst neben der TextAPI auch eine AnnotationAPI, SearchAPI und IndexAPI sowie insbesondere den Text Viewer for Digital Objects (TIDO), der TextAPI-JSON konsumiert und als Frontend einer darauf aufbauenden Web Application verwendet werden kann. Ein Beispiel dafür findet sich hier: https://ahiqar.uni-goettingen.de/arabic-karshuni.html?tido=m5_i0_p0.0-1.0-2.1-3.0

Zentrale Ergebnisse der gemeinsamen Diskussion

#OneAPIToRuleThemAll?

Ausgehend von der Feststellung, dass die diskutierten API-Spezifikationen ein ähnliches Textverständnis zugrundelegen und REST-basiert sind, stellte sich gleich zu Beginn der Diskussionsrunde die Frage, ob die vier verschiedenen Spezifikationen in einen gemeinsamen Standard zusammengeführt werden könnten. 

Dagegen spricht, dass die präsentierten APIs natürlich nicht die Gesamtheit aller Schnittstellen in diesem Bereich darstellen und schon die vier genannten durch die unterschiedlichen Entwicklungs- und Anwendungskontexte verschiedene Fokusse und damit auch unterschiedliche Features mitbringen. Zudem sind manche der Schnittstellen bereits Teil eines größeren Ökosystems, sodass Änderungen hin zu einer gemeinsamen Spezifikation für Inkompatibilitäten und damit nachträglichen Anpassungsaufwand sorgen würden.

Allerdings brächte ein gemeinsamer Standard enorme Vorteile sowohl für Forschende als auch Infrastrukturanbietende mit sich: Durch ein abstraktes und flexibles Textmodell (wie es die bisher betrachteten APIs verwenden) wäre es möglich, einheitlich auf Texte und zugehörige Metadaten unterschiedlichster Editionsprojekte zuzugreifen. Die einmalige Einarbeitung in diesen Standard und die API-Verwendung würde also den Zugang zu einer Fülle von mit viel Mühe und Zeit aufbereitetem Forschungsmaterial erlauben. Mit Sicherheit würde das auch die Nachnutzung dieser Daten fördern. Infrastrukturanbieter:innen müssten gleichzeitig lediglich einen einzigen Standard implementieren und zugehörige Skripte pflegen, was die Etablierung und Verfügbarhaltung dieser Services deutlich erleichtert. Gleiches gilt für Entwickler:innen von Forschungssoftware, die so leichter überblicken könnten, welche Schnittstellen ihr Produkt vielleicht anbieten sollte.

Für die Zusammenführung der verschiedenen Spezifikationen wären dabei natürlich viele Abstimmungen nötig – idealerweise nicht nur zwischen den Entwickler:innen, sondern auch innerhalb der Community. Vielleicht kann die zur Vorbereitung des Workshops erstellte Übersicht der vier Spezifikationen neben der Überblicksfunktion hierfür auch als Diskussionsgrundlage dienen: https://doi.org/10.11588/DATA/4EKAGI (falls Interesse besteht, dort weitere APIs aufzunehmen, gerne melden!). 

Use Cases sammeln

Während der Diskussionsrunden stelle sich mehrmals die Frage, wer genau APIs nutzt und zu welchem Zweck – dies sowohl von Seiten der Wissenschaftler:innen aus, die mögliche Einsatzzwecke und damit Mehrwerte der Schnittstellen kennenlernen wollen, als auch von den Entwickler:innen, die konkrete Fallbeispiele nutzen können, um die API-Spezifikation weiterzuentwickeln und an die Bedarfe der Community anzupassen. Beispielsweise bat Hugh Cayless um Textzeugen mit komplexeren Strukturen aus Editionsprojekten, um sicherstellen zu können, dass das Design des DTS–navigation-Endpunktes die API-Implementierung in einem Projekt nicht behindert. 

Im ersten Schritt könnten die (geplanten oder bereits umgesetzten) Anwendungsfälle über die jeweiligen GitHub-/GitLab-Repositorien oder mittels der auf den API-Webseiten angegebenen Kontaktmöglichkeiten übermittelt werden. Die auf den Webseiten oft schon enthaltenen Informationen zur API-Nutzung in bestimmten Projekten könnten dann noch weiter ausgebaut werden und so vielleicht auch weitere Nachnutzungen inspirieren.

Implementierung einer API-Spezifikation: DTS im TEI Publisher

Der Vortrag von Magdalena Turska und Wolfgang Meier zur Implementierung der DTS-Spezifikation im TEI Publisher stellte den letzten Teil des Workshops dar. In der aktuellen Version 9 des TEI Publishers sind die beiden DTS-Endpunkte collection und document – jeweils zur Einsicht in Dokumentensammlungen und zum Herunterladen von Ressourcen – bereits integriert; in Version 10 soll der fehlende navigation-Endpunkt folgen. Den Nutzenden des TEI Publishers soll es dabei möglich sein, die DTS-Komponente mit wenigen Klicks zu ihrer Editionsapp hinzuzufügen oder abzuwählen, ohne selbst etwas implementieren zu müssen. 

Dies stellt jedoch besondere Herausforderungen an die Entwicklung seitens TEI Publisher, da der navigation-Endpunkt Wissen zur Textstruktur fordert, die je nach Ressource sehr unterschiedlich ausfallen kann. Das aktuell dafür herangezogene TEI-Element citeStructure ist jedoch für die Abbildung sehr komplexer Strukturen nur bedingt geeignet. Magdalena Turska schlug deshalb nach der Darlegung der Schwierigkeiten als eine mögliche Lösung vor, die ODDs (One Document Does it All – das TEI-eigene Schemaformat) derart anzupassen, dass über sie Aussagen zur Textstruktur gewonnen werden können. Damit einher ging die Idee, eine Registry dieser ODD-Dateien und DTS-nutzenden Projekte zu nutzen, da die dafür nötigen Informationen dann ohnehin im TEI Publisher vorlägen. 

Persönliches Fazit

Insgesamt sind meine Kollegen und ich mit vielen Fragen in den Workshop gestartet und mit mindestens so vielen Anregungen auch wieder davon zurückgekommen. Die allgemeine Bereitschaft, Erfahrungen zu teilen, Entwicklungsentscheidungen zu diskutieren und erneut zu durchdenken sowie das große Interesse an einem gemeinsamen Standard haben mich dabei besonders gefreut. Letzteres haben wir zusammen mit dem Wunsch nach mehr Orientierung und Nutzungsbeispielen auch klar als Bedarfe festgestellt. Gelegentlich hatten wir in den Diskussionsrunden den Eindruck, dass sich die Nicht-API-Entwickler:innen noch etwas zurückhielten – vielleicht, weil das Thema neu ist und man sich erst einmal einen Eindruck davon machen wollte. Dass wir dies mit der Kombination aus Vorträgen und Fragerunden unterstützen konnten, ist gut; zukünftige Angebote könnten hier aber vielleicht noch expliziter auf API-Neulinge eingehen. Vielleicht gibt es ja sogar bald Schulungen zu einem gemeinsamen API-Standard… In jedem Fall hoffen wir als Veranstalter, dass alle Teilnehmenden etwas aus dem Workshop für sich mitnehmen konnten, und bedanken uns noch einmal herzlich für die gemeinsame Zeit.

 

Verfasst von Katharina Brückmann, mit freundlicher Unterstützung von Philipp Hegel, Jakub Šimek und Leonhard Maylein.

  1. Siehe Punkt 4.9 in: Sahle, Patrick et al.: „Criteria for Reviewing Scholarly Digital Editions, version 1.1“, abgerufen unter https://www.i-d-e.de/publikationen/weitereschriften/criteria-version-1-1/ am 17.11.2025. ↩︎
Reflektion    , , , , , , ,

Kommentar schreiben