Rezensionen online open |
![]() |
Bibliotheken und Partnereinrichtungen können ab sofort die neue Suchmaske in ihre Homepage integrieren. Mit der Verknüpfung auf folgenden Link erhalten Sie direkten Zugriff auf den umfangreichsten frei zugänglichen Rezensionspool im deutschen Sprachraum:
https://www.biblio.at/rezbib/biblio/rezonline.php
Für Programmierer: Zum Integrieren in ein Bibliotheksprgramm beachten Sie bitte folgende Anweisungen:
V1.0-pre1 2013-01-06
1 Einleitung
„Rezensionen online open“ entstand aus der Zusammenführung der Projekte „Rezensionen Online“ (www.rezensionen.at) und „Katalogisate Online“ (www.katalogisate.at). Die Webservice API bietet direkten Zugriff auf den Datenpool von über 40.000 Rezensionen und 135.000 Katalogisaten (Stand Oktober 2012).
Die API orientiert sich an aktuellen, offenen Standards:
-
REST Paradigma: Zugriff über HTTP GET Requests
- JSON Datenformat: In allen aktuellen Programmiersprachen einfach zu parsen, erweiterbar
- UTF-8 Zeichenkodierung: Keine Einschränkung im Zeichensatz, offen für Internationalisierung
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]