Rezensionen online open
Webservice API

1.1 Nutzungsbedingungen

Für den Zugriff auf die Webservice API ist ein API Key notwendig, der per email an reinhard.ehgartner@biblio.at angefordert werden kann.
Der API Zugriff wird auf einer freiwilligen, fair-use Basis kostenlos zur Verfügung gestellt. Es besteht kein Anspruch auf Erteilung eines Zugriffs, insbesonders behalten wir uns das Recht vor, bei übermäßiger oder missbräuchlicher Verwendung den Zugriff jederzeit ohne Vorankündigung zu beschränken oder zu sperren.

Um eine Sperre durch übermäßige Verwendung zu verhindern, wird dringend angeraten, die Daten lokal zu cachen, insbesondere wenn mit mehr als 1000 Zugriffen pro Tag zu rechnen ist.

Die angebotenen Inhalte stehen unter der Creative Commons Lizenz BY-NC-SA 2.0. Eine Nutzung in kommerziellen Produkte ist nur mit ausdrücklicher, schriftlicher Genehmigung gestattet.

2 HTTP Webservice API

Die API bietet Zugriff auf folgende Funktionen:

1. Mediensuche:

http://ws.biblio.at/rezensionen/v1/suche?key=...&suchkriterien...

Suche nach ISBN/EAN, Autor, Titel, … Liefert Gesamtzahl der gefundenen Medien sowie Katalogisate der Medien und Informationen zu den verfügbaren Rezensionen. Unter den darin enthaltenen URLs können mit weiteren Zugriffen die Rezensionen abgerufen werden.

2. Abruf von Rezension zu zuvor gefundenen Medien:

http://ws.biblio.at/rezensionen/v1/medium/id/<MID>/rezension/id/<RID>?key=...
Bei der Suche nach ISBN/EAN Code werden durch Angabe des Parameters mittext=1 alle Rezensionstexte übertragen, weitere Zugriffe sind in diesem Fall nicht notwendig.

2.1 Aufbau der URLs

Bei allen Zugriffen muss der API-Key als Query Parameter in der Form key=... angegeben werden.
Sonderzeichen und Umlaute müssen als URL-encoded UTF-8 Zeichen übertragen werden.
Beispiel: Suche nach Personen mit Nachname Müller‘:
http://ws.biblio.at/rezensionen/v1/suche?key=1234&nachname=M%C3%BCller

2.2 HTTP-Header / Content Type

Bei allen Zugriffen muss der HTTP-Header Accept: application/json mitgesendet werden.
Beispiel: HTTP-Request für Suche:
GET /rezensionen/v1/suche?key=4242&nachname=M%C3%BCller HTTP/1.1
Host: ws.biblio.at
Accept: application/json

2.3 HTTP Status Codes

Bei einem erfolgreichen Zugriff wird der Status Code 200 (OK) zurückgeliefert. Im Falle eines Fehlers werden die Codes 4xx bzw. 5xx gemeldet.
Die Codes 4xx bzw 5xx treten i.a. bei folgenden Fehlern auf:
400: Ungültiger Zugriff, z.B. Zugriff über das Ende der Liste von Suchergebnissen hinaus
403: Kein oder ungültiger API-Key angegeben
404: Ungültige oder nicht existente URL
503: Server temporär nicht erreichbar

3 API Funktionen

3.1 Mediensuche

Bei der Suche nach Medien können mehrere Kriterien gleichzeitig angegeben werden. Alle Kriterien werden bei der Suche UND-verknüpft.
z.B.: Suche nach Person „Ernst Jandl“:
http://ws.biblio.at/rezensionen/v1/suche?key=1234&vorname=Ernst&nachname=Jandl
Die Suche erfolgt ohne Unterscheidung von Groß-/Kleinschreibung, d.h. „nachname=Schenk“ liefert die gleichen Ergebnisse wie „nachname=schenk“.

3.1.1 Rechtstrunkierung

Durch Anhängen eines „*“ Zeichens (URL-kodiert „%2A“) am Ende wird bei der Suche nach Personen, Titel, Verlag oder Schlagwort eine rechtstrunkierende Suche gestartet.
zB: „nachname=sche%2A“ liefert die Personen Scheer, Scheffel, Schenk, …

3.1.2 Pagination

Wurden mehr als 10 Treffer gefunden, so werden nur die ersten 10 Treffer zurückgeliefert. Die weiteren Treffer können durch Setzen des Parameters start=... (beginnend mit 0) abgerufen werden. Mit dem Parameter count=... kann festgelegt werden wie viele Treffer geliefert werden sollen (erlaubte Werte sind 1 bis 100).
zB: „nachname=schenk&count=25“ liefert die ersten 25 Treffer (1-25)., „nachname=schenk&start=25&count=25“ liefert die nächsten 25 Treffer (26-50)

3.1.3 Suchkriterien und -optionen

isbn=... ISBN-10, ISBN-13 oder EAN Suche. Die Prüfziffer des ISBN/EAN Codes muß gültig sein, Trenner innherhalb der ISBN sind erlaubt (Minus-Zeichen „-“)
mittext=1 Rezensionstext mitliefern, nur bei ISBN/EAN-Suche erlaubt!
vorname=...
nachname=... Autoren-/Personensuche nach Vor- bzw. Nachname
verlag=... Verlagssuche
titel=... Titelsuche
titelmode=fulltext Intelligente Volltext Titelsuche statt exakter (bzw. rechtstrunkierender) Suche verwenden
sw1=...
sw2=...
sw3=... Schlagwortsuche (1 bis 3 Schlagworte möglich).
swmode=or „oder“ Verknüpfung der einzelnen Schlagworte statt „und“ Verknüpfung verwenden.
jahrvon=...
jahrbis=... Erscheinungsjahr von/bis (4-stellige Zahl)

3.1.4 Suchergebnis

Bei einer gültigen Suchanfrage wird ein JSON kodiertes Objekt vom Typ „Medienliste“ zurückgegeben. Es enthält die Gesamtzahl der gefundenen Medien (kann 0 sein, wenn keine Medien gefunden wurden) sowie ein Array der gefundenen Medien (max. 10 bzw durch „count=...“ ausgewählte Anzahl).

3.2 Rezension zu Medium

Mittels des Attributs „url“ im Rezensions-Objekt kann die vollständige Rezension, inklusive Rezensionstext, abgerufen werden.
Im ersten Schritt muss mit Hilfe der Mediensuche die Rezensions-URL ermittelt werden:
{
„total“: 123,
„list“:
[
{
...
„rezensionen“:
[
{
...
„url“: „http://ws.biblio.at/rezensionen/v1/medium/id/123/rezension/id/456“,
...
},
{
...
„url“: „http://ws.biblio.at/rezensionen/v1/medium/id/123/rezension/id/789“,
...
}
]
},
...
]
}

In diesem Beispiel sind zum Medium zwei Rezensionen unter den aufgeführten URLs erreichbar. An die URLs muss der API-Key angehängt werden, die vollständigen URLs lauten damit:
http://ws.biblio.at/rezensionen/v1/medium/id/123/rezension/id/456?key=1234
http://ws.biblio.at/rezensionen/v1/medium/id/123/rezension/id/789?key=1234
Als Ergebnis wird ein JSON-kodiertes Objekt vom Typ „Rezension“ zurückgeliefert.

4 Datenstrukturen

Sofern nicht anders angegeben sind die angeführten Objekt-Attribute als optional zu verstehen, sprich sie können null sein, Arrays können leer sein.
In späteren Versionen können ohne vorherige Ankündigung weitere Objekt-Attribute eingeführt werden, bei der Implementierung sind deshalb unbekannte Attribute zu ignorieren.

4.1 Medienliste

Dieses Objekt wird von der Mediensuche zurückgeliefert.
Attribut Typ Beschreibung
total int Anzahl aller Einträge
list array Medium Medien, Länge des Arrays sowie Auswahl der Medien wird durch Pagination Parameter bestimmt

4.2 Person

Verwendet von Medium in verfasser und personen
Attribut Typ Beschreibung
id int Interne Personen-ID
vorname string Vorname
nachname string Nachname

4.3 Rezension(en)

Verwendet von Medium und in „Rezension zu Medium“ Funktion.
Hinweis: bei der Mediensuche wird das Attribut „text“ auf null gesetzt (ausgenommen ISBN-Suche und Parameter „mittext=1“ ist angegeben).
Attribut Typ Beschreibung
id int Interne Rezensions-ID
autor string Autor der Rezension
text string Rezensionstext
quelle_name string Kürzel der Rezensionsquelle
quelle_name_lang string Name der Rezensionsquelle
quelle_url string URL zur Website der Rezensionsquelle
url string URL zur Rezension

4.4 Medium

Verwendet in Medienliste.
Attribut Typ MAB2
Äquivalent Beschreibung
id int Interne Medium-ID
hst string 331 Hauptsachtitel
ean string 540a/540b ISBN-13 oder EAN Code
isbn10 string 540a/540b ISBN-10 Code
isbnz string (540a) ISBN-Zusatz, wird in MAB2 an 540a angehängt
hstzu string 335 Hauptsachtitel Zusatz
hstan string 310 Ansetzungssachtitel
est string 304 Einheitssachtitel
pst string 341 Parallelsachtitel
fst string 531 Früherer Titel
verl string 412 Verleger
vort string 410 Verlagsort
umf string 433 Umfang
jahr int 425 Erscheinungsjahr
form string 435 Format
aufl string 403 Ausgabebezeichnung
gt1 string 451b Gesamttitelangaben
gt1b string 454 Gesamttitelangaben
gt1z string 455 Gesamttitelangaben
gt2 string 462b Gesamttitelangaben
gt2b string 464 Gesamttitelangaben
ur1b string 360 Unterreihe
fussn string 501 Fußnoten
verfa string 359 Verfasser
verfasser array Person 100,... Verfasser
personen array Person 100b, ... Sonstige beteiligte Personen
schlagworte array string 902 Schlagworte
rezensionen array Rezension 750/751, ... Rezensionen
image_url string URL zu Cover-Image
url string URL zum Medium

[Ende]