6. Rest Schnittstelle
Kapitel hinzufügen

Neben der SOAP Schnittstelle gibt es auch eine REST Schnittstelle, die Request/Response Nachrichten im JSON Format verarbeitet. Dies ist insbesondere für den Aufbau eines Webportals hilfreich, um Anfragen direkt aus der Webseite zu generieren und zu verarbeiten, z.B. mit JavaScript. Es stehen folgende REST Funktiongruppen zur Verfügung:

IRestAccessService

checkPermission

Prüft, ob ein Benutzer ein bestimmtes Recht ausüben darf.

IRestGoobiService

checkDocumentAccess

Gibt eine Aufstellung der erlaubten Zugriffsrechte auf ein gegebenes Dokument zurück.

IRestRepositoryService

getDocument

Gibt die Strukturdaten eines gegebenen Dokuments zurück.

getDocumentList

Liefert einer Liste aller Dokument im Repository.

IRestSearchService

getResultList

Liefert die Trefferliste einer durchgeführten Suche zurück.

searchDocuments

Führt eine Dokumentsuche durch.

IRestSessionService

login

Startet eine Sitzung und meldet den angegebenen Benutzer an.

logout

Meldet den Benutzer ab und schliesst die zugehörige Sitzung.

Die detaillierte Beschreibung der REST Schnittstelle, ihrer Funktionen und Datenstrukturen findet sich in der Javadoc der gleichnamigen Stub-Klassen.

6.1 RESTful Schnittstellen
Abschnitt hinzufügen

Der elektronische Lesesaal MyBib eL (MeL) bietet RESTful Schnittstellen an, über die Nutzer authentifiziert, Datenbestände durchsucht und Dokumentinformationen eingeholt werden können. Im Folgenden werden diese Schnittstellen in Funktion, Aufruf und Rückgabe näher beschrieben.
(Anmerkung: Optionale Parameter sind als solche gekennzeichnet, bei allen weiteren Feldern handelt es sich um Pflichtfelder.)

Stand: MeL Version 2.4.0

6.1.1 Überblick Workflow

Folgende Grafik gibt einen Überblick über den prinzipiellen Ablauf des Erzeugens einer Session und der Dokumentsuche innerhalb der Session. Beachte: Innerhalb einer Session können beliebig viele Abfragen ausgeführt werden, es muss nicht für jede Server-Anfrage eine eigene Session erzeugt werden.

6.1.2 Authentifizierung

Die Authentifizierung eines Nutzers erfolgt über den Session Service, der die Methoden login und logout zur Verfügung stellt. Nach erfolgreichem Login wird serverseitig eine Session für den aktuellen Benutzer generiert, deren Session Id nach dem Aufruf zurück geliefert wird. Diese Session Id wird bei allen weiteren Aufrufen von Methoden und Services der RESTful Schnittstellen benötigt, um die gültige Session eines eingeloggten Nutzers identifizieren zu können (serverseitige Rechteprüfung und Protokollierung), und muss daher stets als Parameter dem Aufruf übergeben werden. Sie setzt sich aus einer zufälligen Zahlen-/Buchstabenkombination zusammen. Die Session ist so lange gültig, bis der Benutzer sich vom System abmeldet oder nach einer bestimmten Zeit der Inaktivität automatisch ausgeloggt wird. Dieser Timeout ist serverseitig konfigurierbar und standardmäßig auf 1 Stunde eingestellt.

6.1.2.1 Login

Beschreibung:
Wird zur Authentifizierung eines Benutzers aufgerufen und prüft, ob dem System ein Benutzer mit der gegebenen Benutzername/Passwort-Kombination bekannt ist. Erzeugt eine Session für den aktuellen Nutzer.

Rückgabe:
Session Id der Sitzung des Nutzers

Parameter:

  • service: session (Name des Services zur Authentifizierung)
  • method: login (Name der beim Login aufzurufenden Methode)
  • login: <currentuser> (Benutzername, Pflichtfeld)
  • password: <currentpassword> (Passwort, Pflichtfeld)

Beispiel Anfrage:

http://<base-url-of-mel>/rest?service=session&method=login&login=<currentuser>&password=<currentpassword>

Beispiel Antwort:

jsonpCallbackFunction({
login:[{
  "sessionId" : "currentsessionid"
}]})

Fehlerfall:
Im Fehlerfall wird eine Fehlermeldung „errorMessage“ als Antwort mit entsprechendem HTTP Status Code ausgeliefert:

jsonpCallbackFunction({
error:[{
  "errorMessage" : <text of error message>
}]})

Fehlermeldungen:

  • „login parameter(s) missing“, Status 400
  • „user <login> could not be found“, Status 401
  • „login/password do not match“, Status 401
  • sonstige Fehler: Status 500
6.1.2.2 Logout

Beschreibung:
Wird am Ende einer Session aufgerufen, um die Session zu schließen und damit den Benutzer vom System abzumelden.

Rückgabe:
Einfache Logout-Meldung

Parameter:

  • service: session (Name des Services zur Authentifizierung)
  • method: logout (Name der beim Logout aufzurufenden Methode)
  • sessionId: <currentsessionid> (siehe Abschnitt Login)

Beispiel Anfrage:

http://<base-url-of-mel>/rest?service=session&method=logout&sessionId=<currentsessionid>

Beispiel Antwort:

jsonpCallbackFunction({logout:[]})

Fehlerfall:
Im Fehlerfall wird eine Fehlermeldung „errorMessage“ als Antwort mit entsprechendem HTTP Status Code ausgeliefert:

jsonpCallbackFunction({
error:[{
  "errorMessage" : "...<text-of-error-message>..."
}]})

Fehlermeldungen:

  • „session id parameter missing“, Status 400
  • „session <sessionId> is invalid“, Status 500
  • sonstige Fehler: Status 500
6.1.2.3 Session Methoden

Session prüfen

Beschreibung:
Wird aufgerufen, um zu prüfen, ob eine Session gültig ist, d.h. der Nutzer ist eingeloggt und die Session ist noch nicht z.B. durch einen Timeout abgelaufen.

Rückgabe:
Meldung, ob die Sitzung gültig ist (valid) oder ungültig (invalid).

Parameter:

  • service: session (Name des Services zur Authentifizierung)
  • method: checkSession (Name der zur Session-Prüfung aufzurufenden Methode)
  • sessionId: <currentsessionid> (Id der zu prüfenden Session)

Beispiel Anfrage:

http://<base-url-of-mel>/rest?service=session&method=checkSession&sessionId=<currentsessionid>

Beispiel Antwort:

jsonpCallbackFunction({
checkSession:[{
  "session" : "<valid|invalid>"
}]})

Fehlerfall:
Im Fehlerfall wird eine Fehlermeldung „errorMessage“ als Antwort mit entsprechendem HTTP Status Code ausgeliefert:

jsonpCallbackFunction({
error:[{
  "errorMessage" : "...<text-of-error-message>..."
}]})

Fehlermeldungen:

  • „session id parameter missing“, Status 400
  • sonstige Fehler: Status 500

Session Alive

Beschreibung:
Wird aufgerufen, um die Gültigkeit einer Session zu verlängern. Beim regulären Aufruf von Methoden des RESTful Services (z.B. Suche oder Dokumentaufruf) geschieht dies automatisch. Um die Gültigkeit einer Session dennoch zu verlängern, so dass sie nicht in den Inaktivitäts-Timeout läuft, kann sessionAlive aufgerufen werden.

Rückgabe:
Einfache SessionAlive Meldung. Bei ungültiger Session wird ein Fehler ausgeliefert (siehe Fehlermeldungen).

Parameter:

  • service: session (Name des Services zur Authentifizierung)
  • method: sessionAlive (Name der zu verlängernden Session)
  • sessionId: <currentsessionid> (Id der zu verlängernden Session)

Beispiel Anfrage:

http://<base-url-of-mel>/rest?service=session&method=sessionAlive&sessionId=<currentsessionid>

Beispiel Antwort:

jsonpCallbackFunction({sessionAlive:[]})

Fehlerfall:
Im Fehlerfall wird eine Fehlermeldung „errorMessage“ als Antwort mit entsprechendem HTTP Status Code ausgeliefert:

jsonpCallbackFunction({
error:[{
  "errorMessage" : "...<text-of-error-message>..."
}]})

Fehlermeldungen:

  • „session id parameter missing“, Status 400
  • „session <sessionId“ is invalid„, Status 500
  • sonstige Fehler: Status 500

6.1.3 Suche

Der Suchservice kann genutzt werden, um den Dokumentenbestand gezielt nach einer Suchanfrage zu durchsuchen. Dokumentenbestand gliedert sich auf in Dokumente, Kapitel und Seiten, die jeweils einzeln durchsucht werden können.
Die Vorgehensweise einer Suchanfrage ist zuerst das Stellen der Anfrage mit dem Suchtext an den Server. Dieser liefert als Antwort eine Result Id und die Anzahl der Suchtreffer an den Aufrufer zurück. Mit dieser Id kann der der Aufrufer nun in einem nächsten Schritt die Suchergebnisse (oder eine Teilmenge) abfragen.

6.1.3.1 Suche nach Dokumenten

Suchanfrage

Beschreibung:
Stellt eine Suchanfrage mit vom Benutzer angegebenen Suchtext an den MeL-Server. In der Treffermenge enthalten sind Dokumente, deren Datenfelder die in der Suche angegebenen Kriterien enthalten. Bei einer Suchanfrage ohne query sind alle Dokumente des elektronischen Lesesaales in der Treffermenge enthalten.

Rückgabe:
Id des Suchergebnisses, Suchanfrage, Anzahl der Ergebnisse.

Parameter:

  • service: search (Name des Services zur Suche)
  • method: searchDocuments (Name der Methode zur Durchführung einer Suche)
  • sessionId: <currentsessionid> (siehe Abschnitt Authentifizierung)
  • query: <suchanfrage> (Text, nach dem der Dokumentenbestand durchsucht werden soll; optional, wenn keine query angegeben ist, werden alle Dokumente als Treffermenge zurückgegeben)
  • sortField: <document_title|document_sortdate|document_medianumber> (Indexfeld, nach dem sortiert werden soll; optional, Standard ist score, d.h. Relevanz)
  • sortDirection: <asc|desc> (Sortierrichtung der Suchergebnisliste, desc (absteigend) oder asc (aufsteigend); optional, Standard ist desc)
  • field: <text|document_title|document_medianumber|document_issue_no|document_barcode|chapter_title|chapter_Schlagwort|…> (Indexfeld, in dem gesucht werden soll; optional, Standard ist text; hängt von Dokumentmetadaten und Server-Konfiguration ab)

Beispiel Anfrage:

http://<base-url-of-mel>/rest?service=search&method=searchDocuments&sessionId=<currentsessionid>&query=<currentquery>&sortField=<sortfield>&sortDirection=desc&field=text

Beispiel Antwort:

jsonpCallbackFunction({
resultInfo:[{
  "resultId" : "currentresultid",
  "query" : "currentquery",
  "numberOfResults" : 11,
  "isCompleted" : true
}]})

Fehlerfall:
Im Fehlerfall wird eine Fehlermeldung „errorMessage“ als Antwort mit HTTP Status Code 500 ausgeliefert:

jsonpCallbackFunction({
error:[{
  "errorMessage" : "...<text-of-error-message>..."
}]})

Fehlermeldungen:

  • „session id parameter missing“, Status 400
  • „session <sessionId> is invalid“, Status 500
  • sonstige Fehler: Status 500

Suchergebnisse

Beschreibung:
Über die Methode getResultList können Informationen zu den Suchtreffern (oder einer Untermenge, z.B. Treffer 10-20) abgefragt werden. Die Antwort dieser Anfrage beinhaltet zu den gewünschten Treffern der Suchergebnisliste u.a. die Metadaten zu den jeweiligen Treffer-Dokumenten:

  • Titel
  • Signatur
  • Mediennummer
  • Seitenanzahl
  • Information, ob das Dokument per Weboberfläche angezeigt werden
  • Informationen zur ersten Seite des Dokumentes
  • Seiten-Id
  • Seitennummer
  • URL zum Thumbnail
  • URL zum Seitenbild.

Rückgabe:
Auflistung der Suchtreffer mit Metadaten der Dokumente und Referenzen auf Thumbnail und Seitenbild der ersten Seite. Bei den ausgelieferten Thumbnail- und Seitenbild-URLs handelt es sich um generische URLs ohne sessionId, die zur tatsächlichen Abfrage noch als entsprechender Parameter der URL hinzugefügt werden müssen. Die Größe der ausgelieferten Bilder/Thumbnails wird serverseitig konfiguriert.

Anmerkungen zu Seitenbildern/Thumbnails:
Zu jedem Suchtreffer werden die URLs zu Seitenbild und Thumbnail der ersten Seite des Dokumentes angegeben. Wie bei allen weiteren Methoden der RESTful Schnittstellen ist bei Aufruf einer dieser URLs die sessionId als Parameter mit anzugeben, damit serverseitig beim Aufruf des Bildes entsprechende Berechtigungen für die aktuelle Benutzersitzung ausgewertet werden können.

Parameter:

  • service: search (Name des Services zur Suche)
  • method: getResultList (Name der Methode zum Abruf der Suchergebnisse zu einer Suchanfrage)
  • sessionId: currentsessionid (gültige Session Id, siehe 1 Authentifizierung)
  • resultId: currentresultid (gültige id des Ergebnisses aus Antwort des zuvor erfolgten Suchaufrufs (siehe 2.1 Suchanfrage))
  • from: Positionsnummer des ersten Treffers, der zurückgegeben werden soll (null-basiert); optional, Standard ist 0
  • to: Positionsnummer des ersten Treffers, der nicht zurückgegeben werden soll (null-basiert); optional, Standard ist 10000

Beispiel Anfrage:

http://<base-url-of-mel>/rest?service=search&method=getResultList&sessionId=<currentsessionid>&resultId=<currentresultid>&from=0&to=10

Beispiel Antwort:

jsonpCallbackFunction({
resultList:[{
  "resultEntries" : [ {
    "title" : "Title1",
    "signature" : "Sig1",
    "medianumber" : "1",
    "pageCount" : 2,
    "webservicePermissionRead" : "allow",
    "firstPage" : {
      "pageId" : "firstpageid1",
      "pageNr" : 1,
      "thumbnailUrl" : "http://<base-url-of-mel>/repository?method=getImage&pageId=firstpageid",
      "imageUrl" : "http://<base-url-of-mel>/repository?method=getImage&pageId=firstpageid"
    },
    "abstract" : "Abstract1"
  }, {
    "title" : "Title2",
    "signature" : "Sig2",
    "medianumber" : "11",
    "pageCount" : 4,
    "webservicePermissionRead" : "allow",
    "firstPage" : {
      "pageId" : "firstpageid2",
      "pageNr" : 1,
      "thumbnailUrl" : "http://<base-url-of-mel>/repository?method=getImage&pageId=firstpageid2",
      "imageUrl" : "http://<base-url-of-mel>/repository?method=getImage&pageId=firstpageid2"
    },
    "abstract" : "Abstract2"
  } ],
  "resultId" : "currentresultid",
  "from" : 0,
  "to" : 1
}]})

Fehlerfall:
Im Fehlerfall wird eine Fehlermeldung „errorMessage“ als Antwort mit HTTP Status Code 500 ausgeliefert:

jsonpCallbackFunction({
error:[{
  "errorMessage" : "...<text-of-error-message>..."
}]})

Fehlermeldungen:

  • „session id parameter missing“, Status 400
  • „session <sessionId> is invalid“, Status 500
  • „unknown result id“, Status 500
6.1.3.2 Suche nach Kapiteln

Suchanfrage

Beschreibung:
Stellt eine Suchanfrage nach Kapiteln mit vom Benutzer angegebenen Suchtext an den MeL-Server. In der Treffermenge enthalten sind Kapiteltreffer, deren Datenfelder die in der Suche angegebenen Kriterien enthalten. Bei einer Suchanfrage ohne query sind alle im Dokumentbestand des elektronischen Lesesaales enthaltenen Kapitel in der Treffermenge enthalten.

Rückgabe:
Id des Suchergebnisses, Suchanfrage, Anzahl der Ergebnisse.

Parameter:

  • service: search (Name des Services zur Suche)
  • method: searchChapters (Name der Methode zur Durchführung einer Suche)
  • sessionId: <currentsessionid> (siehe Abschnitt Authentifizierung)
  • query: <suchanfrage> (Text, nach dem der Dokumentenbestand durchsucht werden soll; optional, wenn keine query angegeben ist, werden alle Dokumente als Treffermenge zurückgegeben)
  • sortField: <document_title|document_sortdate|document_medianumber> (Indexfeld, nach dem sortiert werden soll; optional, Standard ist score, d.h. Relevanz)
  • sortDirection: <asc|desc> (Sortierrichtung der Suchergebnisliste, desc (absteigend) oder asc (aufsteigend); optional, Standard ist desc)
  • field: <text|document_title|document_medianumber|document_issue_no|document_barcode|chapter_title|chapter_Schlagwort|…> (Indexfeld, in dem gesucht werden soll; optional, Standard ist text; hängt von Dokumentmetadaten und Server-Konfiguration ab)

Beispiel Anfrage:

http://<base-url-of-mel>/rest?service=search&method=searchChapters&sessionId=<currentsessionid>&query=<currentquery>&sortField=<sortfield>&sortDirection=desc&field=text

Beispiel Antwort:

jsonpCallbackFunction({
resultInfo:[{
  "resultId" : "currentresultid",
  "query" : "currentquery",
  "numberOfResults" : 11,
  "isCompleted" : true
}]})

Fehlerfall:
Im Fehlerfall wird eine Fehlermeldung „errorMessage“ als Antwort mit HTTP Status Code 500 ausgeliefert:

jsonpCallbackFunction({
error:[{
  "errorMessage" : "...<text-of-error-message>..."
}]})

Fehlermeldungen:

  • „session id parameter missing“, Status 400
  • „session <sessionId> is invalid“, Status 500
  • sonstige Fehler: Status 500

Suchergebnisse

Beschreibung:
Über die Methode getChapterResultList können Informationen zu den Suchtreffern (oder einer Untermenge, z.B. Treffer 10-20) abgefragt werden. Die Antwort dieser Anfrage beinhaltet zu den gewünschten Kapiteltreffern der Suchergebnisliste u.a. die Metadaten zu den jeweiligen Treffer-Dokumenten: Titel, Signatur, Mediennummer, Seitenanzahl, Information, ob das Dokument per Weboberfläche angezeigt werden darf, zur ersten Seite des Dokumentes die Seiten-Id, Seitennummer, URL zum Thumbnail und zum Seitenbild.

Rückgabe:
Auflistung der Suchtreffer mit Metadaten der Dokumente und Referenzen auf Thumbnail und Seitenbild der ersten Seite. Bei den ausgelieferten Thumbnail- und Seitenbild-URLs handelt es sich um generische URLs ohne sessionId, die zur tatsächlichen Abfrage noch als entsprechender Parameter der URL hinzugefügt werden müssen. Die Größe der ausgelieferten Bilder/Thumbnails wird serverseitig konfiguriert.

Anmerkungen zu Seitenbildern/Thumbnails:
Zu jedem Suchtreffer werden die URLs zu Seitenbild und Thumbnail der ersten Seite des Kapitels angegeben. Wie bei allen weiteren Methoden der RESTful Schnittstellen ist bei Aufruf einer dieser URLs die sessionId als Parameter mit anzugeben, damit serverseitig beim Aufruf des Bildes entsprechende Berechtigungen für die aktuelle Benutzersitzung ausgewertet werden können.

Parameter:

  • service: search (Name des Services zur Suche)
  • method: getChapterResultList (Name der Methode zum Abruf der Suchergebnisse zu einer Kapitelsuchanfrage)
  • sessionId: currentsessionid (gültige Session Id, siehe 1 Authentifizierung)
  • resultId: currentresultid (gültige id des Ergebnisses aus Antwort des zuvor erfolgten Suchaufrufs (siehe 2.1 Suchanfrage))
  • from: Positionsnummer des ersten Treffers, der zurückgegeben werden soll (null-basiert); optional, Standard ist 0
  • to: Positionsnummer des ersten Treffers, der nicht zurückgegeben werden soll (null-basiert); optional, Standard ist 10000

Beispiel Anfrage:

http://<base-url-of-mel>/rest?service=search&method=getChapterResultList&sessionId=<currentsessionid>&resultId=<currentresultid>&from=0&to=10

Beispiel Antwort:

jsonpCallbackFunction({
resultList:[{
  "resultEntries" : [ {
    "title" : "Title1",
    "signature" : "Sig1",
    "medianumber" : "1",
    "pageCount" : 2,
    "webservicePermissionRead" : "allow",
    "firstPage" : {
      "pageId" : "firstpageid1",
      "pageNr" : 1,
      "thumbnailUrl" : "http://<base-url-of-mel>/repository?method=getImage&pageId=firstpageid",
      "imageUrl" : "http://<base-url-of-mel>/repository?method=getImage&pageId=firstpageid"
    },
    "abstract" : "Abstract1"
  }, {
    "title" : "Title2",
    "signature" : "Sig2",
    "medianumber" : "11",
    "pageCount" : 4,
    "webservicePermissionRead" : "allow",
    "firstPage" : {
      "pageId" : "firstpageid2",
      "pageNr" : 1,
      "thumbnailUrl" : "http://<base-url-of-mel>/repository?method=getImage&pageId=firstpageid2",
      "imageUrl" : "http://<base-url-of-mel>/repository?method=getImage&pageId=firstpageid2"
    },
    "abstract" : "Abstract2"
  } ],
  "resultId" : "currentresultid",
  "from" : 0,
  "to" : 1
}]})

Fehlerfall:
Im Fehlerfall wird eine Fehlermeldung „errorMessage“ als Antwort mit HTTP Status Code 500 ausgeliefert:

jsonpCallbackFunction({
error:[{
  "errorMessage" : "...<text-of-error-message>..."
}]})

Fehlermeldungen:

  • „session id parameter missing“, Status 400
  • „session <sessionId> is invalid“, Status 500
  • „unknown result id“, Status 500
6.1.3.3 Suche nach Seiten

Suchanfrage

Beschreibung:
Stellt eine Suchanfrage nach Seiten mit vom Benutzer angegebenen Suchtext an den MeL-Server. In der Treffermenge enthalten sind Seitentreffer, deren Datenfelder die in der Suche angegebenen Kriterien enthalten. Bei einer Suchanfrage ohne query sind im Dokumentbestand des elektronischen Lesesaals enthaltenen Seiten in der Treffermenge enthalten.

Rückgabe:
Id des Suchergebnisses, Suchanfrage, Anzahl der Ergebnisse.

Parameter:

  • service: search (Name des Services zur Suche)
  • method: searchPages (Name der Methode zur Durchführung einer Suche)
  • sessionId: <currentsessionid> (siehe Abschnitt Authentifizierung)
  • query: <suchanfrage> (Text, nach dem der Dokumentenbestand durchsucht werden soll; optional, wenn keine query angegeben ist, werden alle Dokumente als Treffermenge zurückgegeben)
  • sortField: <document_title|document_sortdate|document_medianumber> (Indexfeld, nach dem sortiert werden soll; optional, Standard ist score, d.h. Relevanz)
  • sortDirection: <asc|desc> (Sortierrichtung der Suchergebnisliste, desc (absteigend) oder asc (aufsteigend); optional, Standard ist desc)
  • field: <text|document_title|document_medianumber|document_issue_no|document_barcode|chapter_title|chapter_Schlagwort|…> (Indexfeld, in dem gesucht werden soll; optional, Standard ist text; hängt von Dokumentmetadaten und Server-Konfiguration ab)

Beispiel Anfrage:

http://<base-url-of-mel>/rest?service=search&method=searchPages&sessionId=<currentsessionid>&query=<currentquery>&sortField=<sortfield>&sortDirection=desc&field=text

Beispiel Antwort:

jsonpCallbackFunction({
resultInfo:[{
  "resultId" : "currentresultid",
  "query" : "currentquery",
  "numberOfResults" : 11,
  "isCompleted" : true
}]})

Fehlerfall:
Im Fehlerfall wird eine Fehlermeldung „errorMessage“ als Antwort mit HTTP Status Code 500 ausgeliefert:

jsonpCallbackFunction({
error:[{
  "errorMessage" : "...<text-of-error-message>..."
}]})

Fehlermeldungen:

  • „session id parameter missing“, Status 400
  • „session <sessionId> is invalid“, Status 500
  • sonstige Fehler: Status 500

Suchergebnisse

Beschreibung:
Über die Methode getPageResultList können Informationen zu den Seitensuchtreffern (oder einer Untermenge, z.B. Treffer 10-20) abgefragt werden. Die Antwort dieser Anfrage beinhaltet zu den gewünschten Treffern der Suchergebnisliste u.a. die Metadaten zu den jeweiligen Treffer-Dokumenten: Titel, Signatur, Mediennummer, Seitennummer, Seitenanzahl im Dokument, Dokumenttitel, Kapiteltitel, Abstract, Information, ob das Dokument per Weboberfläche angezeigt werden darf.

Rückgabe:
Auflistung der Suchtreffer mit Metadaten der Dokumente und Referenzen auf Thumbnail und Seitenbild der ersten Seite

Parameter:

  • service: search (Name des Services zur Suche)
  • method: getPageResultList (Name der Methode zum Abruf der Suchergebnisse zu einer Seitensuchanfrage)
  • sessionId: currentsessionid (gültige Session Id, siehe 1 Authentifizierung)
  • resultId: currentresultid (gültige id des Ergebnisses aus Antwort des zuvor erfolgten Suchaufrufs (siehe 2.1 Suchanfrage))
  • from: Positionsnummer des ersten Treffers, der zurückgegeben werden soll (null-basiert); optional, Standard ist 0
  • to: Positionsnummer des ersten Treffers, der nicht zurückgegeben werden soll (null-basiert); optional, Standard ist 10000

Beispiel Anfrage:

http://<base-url-of-mel>/rest?service=search&method=getPageResultList&sessionId=<currentsessionid>&resultId=<currentresultid>&from=0&to=10

Beispiel Antwort:

jsonpCallbackFunction({
resultList:[{
  "resultEntries" : [ {
    "pageId" : "pageid1",
    "pagenumber" : 1,
    "medianumber" : "1",
    "restservicePermissionRead" : "allow",
    "docTitle" : "Title 1",
    "chapterTitle" : "Chapter 1",
    "pageCount" : 100,
    "abstract" : ""
  }, {
...
  } ],
  "resultId" : "currentresultid",
  "from" : 0,
  "to" : 1
}]})

Fehlerfall:
Im Fehlerfall wird eine Fehlermeldung „errorMessage“ als Antwort mit HTTP Status Code 500 ausgeliefert:

jsonpCallbackFunction({
error:[{
  "errorMessage" : "...<text-of-error-message>..."
}]})

Fehlermeldungen:

  • „session id parameter missing“, Status 400
  • „session <sessionId> is invalid“, Status 500
  • „unknown result id“, Status 500

6.1.4 Dokumente

Über den Repository-Service können inhaltliche bzw. strukturelle Informationen über ein Dokument eingeholt werden.

6.1.4.1 Dokumenteninformationen (JSON)

Beschreibung:
Liefert sämtliche Seiten eines Dokumentes zurück (Seiten Ids und Referenzen auf Thumbnails und Seitenbilder) und abhängig vom Dokumentenformat Kapitel- oder Artikelinformationen.

Parameter:

  • service: repository
  • method: getDocument
  • sessionId: currentsessionid
  • medianumber: currentmedianumber
  • scale: <scaleImageSizeParameter>, (optional, 0..1, default: configurable in admin tool)
  • quality: <scaleImageQualityParameter> (optional, 0..1, default: configurable in admin tool)

Beispiel:

http://<base-url-of-mel>/rest?service=repository&method=getDocument&sessionId=currentsessionid&medianumber=currentmedianumber

Antwort:

jsonpCallbackFunction({
getDocument:[{
  "title" : "Title1",
  "pages" : [ {
    "pageId" : "pageid1",
    "pageNr" : 1,
    "thumbnailUrl" : "http://<base-url-of-mel>/repository?method=getImage&pageId=pageid1&scale=80x160&quality=0.7",
    "imageUrl" : "http://<base-url-of-mel>/repository?method=getImage&pageId=0005014ae4189513a694883a1709c1760522c56&scale=0.6&quality=0.7"
  }, {
    "pageId" : "pageid2",
    "pageNr" : 2,
    "thumbnailUrl" : "http://<base-url-of-mel>/repository?method=getImage&pageId=pageid2&scale=80x160&quality=0.7",
    "imageUrl" : "http://<base-url-of-mel>/repository?method=getImage&pageId=pageid2&scale=0.6&quality=0.7"
  } ],
  "chapters" : [ {
    "name" : "chaptername1",
    "pageIds" : [ "page1" ]
  }, {
    "name" : "chasptername2",
    "pageIds" : [ "pageid2" ]
  } ],
  "articles" : [ ]
}]})

Im Fehlerfall wird eine Fehlermeldung „errorMessage“ als Antwort mit HTTP Status Code 500 ausgeliefert:

jsonpCallbackFunction({
error:[{
  "errorMessage" : "...<text-of-error-message>..."
}]})

Fehlermeldungen:

  • „session id parameter missing“, Status 400
  • „session <sessionId> is invalid“, Status 500
  • „medianumber parameter missing“, Status 500
  • „document with medianumber <medianumber> not found“, Status 500
  • „permission denied“, Status 500
6.1.4.2 Dokumenteninformationen (XML)

Beschreibung:
Liefert Metadaten und Strukturdaten (Kapitel, Seiten) eines Dokumentes zurück. Das Format ist größtenteils identisch zu „IWC-XML“ (von BCS-2 erzeugtes XML), es unterscheidet sich lediglich darin, dass „page“-Nodes nicht das Attribut „file“ (für den Dateinamen des Seitenbildes beim Import) haben, sondern stattdessen das Attribut „id“, welches die jeweilige Seiten-Id im MeL darstellt und zur Zusammenstellung der Seitenbild-URL genutzt werden kann (Beispiel einer solchen URL siehe unter 3.1).

Parameter:

  • service: repository
  • method: getXmlDocument
  • sessionId: currentsessionid
  • medianumber: currentmedianumber

Beispiel:

http://<base-url-of-mel>/rest?service=repository&method=getDocument&sessionId=currentsessionid&medianumber=currentmedianumber

Antwort:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<order>
    <o_info>
        <o_title>Zeitschrift des Deutschen und des Österreichischen Alpenvereins</o_title>
        <o_identifier/>
        <o_year>1872</o_year>
        <o_editioninfo/>
        <o_barcode>142111406</o_barcode>
        <o_medianumber>85525187025dbf8b006dbd627d015236634d3c006524</o_medianumber>
        <o_publisher/>
    </o_info>
    <e_data>
        <e_property name="document.format">bcs2</e_property>
        <e_property name="issue_no"/>
        <e_property name="document.text">true</e_property>
    </e_data>
    <content>
        <section name="Umschlag vorne" level="1">
            <page id="0002322d8be02221d004eb5ba468d5567d1a769">
                <p_name>Seite 1</p_name>
                <p_number/>
                <p_type/>
            </page>
        </section>
        <section name="Titelblatt" level="1">
            <page id="0002324a47e104ba619452da3f1d222b297d136">
                <p_name>Seite 2</p_name>
                <p_number>2</p_number>
                <p_type/>
            </page>
            <page id="0002325604878aed633462a9e06fb1fbcb09d58">
                <p_name>Seite 3</p_name>
                <p_number>3</p_number>
                <p_type/>
                <e_data>
                    <e_property name="page.text">OCR</e_property>
                </e_data>
            </page>
        </section>
        ...
    </content>
</order>        

6.2 RESTful Schnittstellen für Kicker
Abschnitt hinzufügen

(war MyBib eL: 5 Suche nach Datum und Nachbarn)

Beschreibung:
Liefert Dokument(e) für ein angegebenes Datum zurück (eines, mehrere, keines), einschließlich einer parametrisierbaren Anzahl von direkten Vorgängern und Nachfolgern (sodenn vorhanden) zu diesem Datum.

Parameter:

  • service: search
  • method: searchDocumentNeighborsByDate
  • date: Datum im Format yyyyMMdd
  • docsBefore: Anzahl der Dokumente, die direkt vor dem Datum gefunden werden sollen
  • docsAfter: Anzahl der Dokumente, die direkt nach dem Datum gefunden werden sollen

Beispiel:

http://<base-url-of-mel>/rest?service=search&method=searchDocumentNeighborsByDate&date=19630107&docsBefore=5&docsAfter=5

Antwort:

jsonpCallbackFunction({
resultInfo:[{
  "numberOfResultsForDate" : 1,
  "numberOfResultsBeforeDate" : 1,
  "numberOfResultsAfterDate" : 2,
  "resultEntriesForDate" : [ {
    "title" : "Kicker-Sportmagazin",
    "signature" : "19631A",
    "medianumber" : "19631A",
    "pageCount" : 24,
    "restservicePermissionRead" : "",
    "numdate" : "19630107",
    "firstPage" : {
      "pageId" : "0000001abcc6a36f6e94333b16107b0d0240191",
      "pageNr" : 1,
      "thumbnailUrl" : "http://localhost:8080/kicker/repository?method=getImage&pageId=0000001abcc6a36f6e94333b16107b0d0240191&scale=80x160&quality=0.7",
      "imageUrl" : "http://localhost:8080/kicker/repository?method=getImage&pageId=0000001abcc6a36f6e94333b16107b0d0240191&scale=0.6&quality=0.7"
    },
    "abstract" : ""
  } ],
  "resultEntriesBeforeDate" : [ {
    "title" : "Kicker-Sportmagazin",
    "signature" : "1976001",
    "medianumber" : "1976001",
    "pageCount" : 48,
    "restservicePermissionRead" : "",
    "numdate" : "",
    "firstPage" : {
      "pageId" : "00000954be838f1c96d414da30e8e382693a23f",
      "pageNr" : 1,
      "thumbnailUrl" : "http://localhost:8080/kicker/repository?method=getImage&pageId=00000954be838f1c96d414da30e8e382693a23f&scale=80x160&quality=0.7",
      "imageUrl" : "http://localhost:8080/kicker/repository?method=getImage&pageId=00000954be838f1c96d414da30e8e382693a23f&scale=0.6&quality=0.7"
    },
    "abstract" : ""
  } ],
  "resultEntriesAfterDate" : [ {
    "title" : "Kicker-Sportmagazin",
    "signature" : "1981002",
    "medianumber" : "1981002",
    "pageCount" : 72,
    "restservicePermissionRead" : "",
    "numdate" : "19810105",
    "firstPage" : {
      "pageId" : "0000284dd4daa1f74ed4cd9b975f7ec4455899b",
      "pageNr" : 1,
      "thumbnailUrl" : "http://localhost:8080/kicker/repository?method=getImage&pageId=0000284dd4daa1f74ed4cd9b975f7ec4455899b&scale=80x160&quality=0.7",
      "imageUrl" : "http://localhost:8080/kicker/repository?method=getImage&pageId=0000284dd4daa1f74ed4cd9b975f7ec4455899b&scale=0.6&quality=0.7"
    },
    "abstract" : ""
  }, {
    "title" : "Kicker-Sportmagazin",
    "signature" : "1988001",
    "medianumber" : "1988001",
    "pageCount" : 64,
    "restservicePermissionRead" : "",
    "numdate" : "19880104",
    "firstPage" : {
      "pageId" : "0000522c5470e89cbd24cb9b739f83cf3b009f2",
      "pageNr" : 1,
      "thumbnailUrl" : "http://localhost:8080/kicker/repository?method=getImage&pageId=0000522c5470e89cbd24cb9b739f83cf3b009f2&scale=80x160&quality=0.7",
      "imageUrl" : "http://localhost:8080/kicker/repository?method=getImage&pageId=0000522c5470e89cbd24cb9b739f83cf3b009f2&scale=0.6&quality=0.7"
    },
    "abstract" : ""
  } ]
}]})