×

REST-API

Die Transkribus-Anwendung kommuniziert mit dem Server über eine Reihe von RESTful-Service-Methoden.

Visualisierung mit SWADL

  • Die vollständige Definition ist in der Datei zu finden: anwendung.wadl
  • Visualisiert mit Swadl
  • Die Parameter für alle im Folgenden beschriebenen Methoden finden Sie in dieser Dienstbeschreibungsdatei.

Anmeldung

Die meisten Methoden erfordern, dass der Benutzer bei den Diensten angemeldet ist, was durch POSTing der Benutzeranmeldeinformationen an die Login-Methode erreicht wird:

https://transkribus.eu/TrpServer/rest/auth/login

Die Methode liefert eine XML mit dem Benutzerprofil und den Sammlungen, auf die dieser Benutzer zugreifen darf.
Nachfolgende Anfragen an den Dienst müssen dann die Session-ID aus dem XML entweder in:

  • Der HTTP-Header als Cookie namens "JSESSIONID"
  • Der Anfrageparameter "JSESSIONID"

Sammlungen

Sobald ein Benutzer authentifiziert ist, können die Sammlungen, für die der Benutzer Zugriffsrechte hat, über die folgenden Aufrufe aufgelistet werden:

https://transkribus.eu/TrpServer/rest/collections/list

Der Aufruf gibt eine Liste mit Sammlungen zurück, wobei jedes Objekt die Sammlungs-ID, den Sammlungsnamen und die Rolle des aktuellen Benutzers in dieser Sammlung enthält.

Dokumente in einer Sammlung können analog per GET-Anfrage aufgelistet werden:

https://transkribus.eu/TrpServer/rest/collections/{collection-ID}/list

Dieser Aufruf gibt eine Liste von Dokument-Metadaten-Objekten zurück.

Um ein komplettes Dokument abzurufen, muss man Folgendes GETEN:

https://transkribus.eu/TrpServer/rest/collections/{collection-ID}/{document-ID}/fulldoc

Das zurückgegebene Objekt besteht aus den Metadaten des Dokuments und der kompletten Seitenliste, wobei jede Seite unter anderem Attribute enthält:

  • Ein Link auf das Seitenbild
  • Eine Liste von Transkriptdateien, in der jedes Transkript enthalten ist:
    • Ein Link zur XML-Datei der Seite
    • Die ID und der Name des verantwortlichen Benutzers
    • Ein Zeitstempel
    • Der Bearbeitungsstatus des Transkripts, z. B. NEW, IN_PROGRESS, DONE, FINAL

Für das POSTEN einer neuen PAGE-XML für eine Seite, um die Transkription zu aktualisieren, wird der folgende Pfad angegeben:

https://transkribus.eu/TrpServer/rest/collections/{collection-ID}/{doc-ID}/{pageNr}/text

Die Methode nimmt die Abfrageparameter entgegen:

  • status: Der Bearbeitungsstatus des neuen Transkripts (Werte siehe oben)
  • overwrite: true oder false. Gibt an, ob die letzte Version überschrieben werden soll oder nicht. Das Überschreiben funktioniert nur, wenn die letzte Version von demselben Benutzer gespeichert wurde und der Bearbeitungsstatus nicht "NEU" ist.

Jobs

Alle Verarbeitungsaufgaben, wie z. B. Dokumentenerstellung, Layoutanalyse, HTR-Verarbeitung, OCR-Verarbeitung usw., werden als Threads (Jobs) auf dem Server ausgeführt. Jeder Job hat einen Status und kann überwacht und abgebrochen werden. Eine Job-Liste kann unter abgerufen werden:

https://transkribus.eu/TrpServer/rest/jobs/list

Aufträge sind entweder persistent, z. B. Dokumentenerstellung, HTR usw., oder nicht persistent, z. B. Layout-Analyseaufträge. Erstere werden in der Datenbank gespeichert, während letztere nur im Speicher gehalten werden und nach 1 Stunde oder bei einem Neustart des Servers aus der Jobliste entfernt werden.
Die Details zu einem bestimmten Auftrag können unter abgerufen werden:

https://transkribus.eu/TrpServer/rest/jobs/{job-ID}

Um einen Auftrag abzubrechen, muss eine POST-Anfrage an den folgenden Pfad gesendet werden:

https://transkribus.eu/TrpServer/rest/jobs/{job-ID}/kill

Wenn ein Auftrag die Verarbeitung mehrerer Seiten umfasst, z. B. eine Layoutanalyse oder ein HTR-Prozess, und es Probleme mit bestimmten Seiten gab, können Details mit GET-Anfragen an abgefragt werden:

https://transkribus.eu/TrpServer/rest/jobs/{job-ID}/errors

OCR

https://transkribus.eu/TrpServer/rest/recognition/ocr?collId={collection-ID}&id={doc-ID}&pages={pageNr}

POST an diesen Pfad startet einen OCR-Job für eine bestimmte Dokumentseite. Die Antwort enthält die Job-ID des OCR-Jobs, mit der der Jobstatus abgefragt werden kann (siehe Abschnitt Jobs).

Suche

Suche nach erkanntem Text mit dem SOLR-Index:

GET

https://transkribus.eu/TrpServer/rest/search/fulltext?query=XXX&type=LinesLc&filter=collectionId:1234

Parameter: query="Suchbegriff" type="wo gesucht werden soll" ("LinesLc" sucht in erkanntem Text, ohne Groß-/Kleinschreibung zu berücksichtigen) filter="Filteroptionen" (standardmäßig werden alle Sammlungen mit Zugriff des Benutzers durchsucht, "collectionId:XXXX" liefert nur Ergebnisse aus der gewählten Sammlung)