REST-API

Mithilfe der VLB-REST-API können Sie VLB-Daten schnell und einfach in einer Anwendung nach eigenen Vorstellungen anzeigen lassen. Als schnelle Webschnittstelle bietet sie eine direkte Recherchemöglichkeit im VLB und macht den aufwendigen Aufbau einer eigenen Artikeldatenbank überflüssig. Die VLB-REST-API eignet sich somit hervorragend zur Anbindung von Bibliografier- oder Warenwirtschaftssystemen, genauso wie für die Anbindung von Online-Anwendungen wie Webshops.

Die VLB-REST-API bietet die folgenden Funktionen.

• Produktsuche
• Produktdetailabruf
• Mediendateiabruf

Die VLB-REST-API baut auf die REST-Technologie (Representational State Transfer) auf und nutzt als Authentifizierungsmethode OAuth2. Jeder Datenbezieher erhält vom VLB Zugangsdaten, die je nach festgelegter Berechtigung einen Zugriff auf die freigeschalteten VLB-Daten ermöglichen.

Für die Produktrecherche stehen eine Schnellsuche zur Eingabe beliebiger Suchbegriffe (ISBN, Autor etc.) sowie eine boolesche Suche bereit. Die frei kombinierbaren booleschen Suchkriterien sind:

• Suchkriterien:
  • Produktnummer,
  • Titel- und Untertitel,
  • Autor,
  • Verlag,
  • Schlagwort,
  • thema-Klassifikation,
  • Warengruppe,
  • Erscheinungsjahr,
  • Sprache,
  • Produktform,
  • Produkttyp,
  • Reihen und Hierarchien,
  • Zugangs- und letztes Änderungsdatum
• Weitere Filtermöglichkeiten:
  • aktive und archivierte Titel,
  • Sortierung nach verschiedenen Kriterien

Beispielsweise kann eine Suche nach dem Verlag und dem Erscheinungsdatum kombiniert werden mit deren Hilfe sich z. B. eine Liste aller Titel des Ullstein-Verlages mit Erscheinungsjahr 2010 ermitteln lässt. Die Syntax der booleschen Suche entspricht der auf VLB-Online eingesetzten Suchsyntax.

Jede Suchanfrage liefert eine konfigurierbare Trefferliste im JSON Format. Das JSON-Format überzeugt durch seine Einfachheit und geringes Datenvolumen. Weitere Informationen zum Stellen einer Suchanfrage sowie Formatdetails für die Datenrückgabe entnehmen Sie bitte der VLB-REST-API Spezifikation.

Wenn Sie mehr zu einem Produkt Ihrer Trefferliste erfahren möchten, können Detailinformationen zu diesem abgerufen werden. Sämtliche Informationen zu einem Produkt können über eine API-Anfrage unter Angabe der GTIN-13 oder der VLB-ID (32-stellige vom VLB vergebene Identifikationsnummer) abgerufen werden.

Die Detailproduktdaten stehen in zwei Datenformaten zur Verfügung

• ONIX
  • verfügbar in ONIX Version 2.1 sowie ONIX 3 (hier finden Sie Informationen zur Umstellung auf ONIX 3.1)
  • enthält alle vom VLB unterstützten ONIX-Elemente
• JSON
  • enthält alle in ONIX enthaltenen Produktinformationen sowie weitere durch das VLB angereicherte Angaben, wie Lieferbarkeitsinformationen verschiedener Auslieferer
  • im Vergleich zum ONIX-Format ist JSON leichtgewichtiger – Formatdetails entnehmen Sie bitte der API-Spezifikation

Sie können sich über einen eigenen REST-API-Aufruf eine Liste der produktzugehörigen Mediendateienlinks im JSON-Format ausgeben lassen. Für den Abruf und die Anzeige der Mediendateien sind die GTIN-13 (für Cover) bzw. die eindeutige Mediendatei-ID sowie die Berechtigung zur Anzeige der Mediendateien notwendig. Formatdetails entnehmen Sie bitte der API-Spezifikation.

Tipps, wie Sie Mediendateien performant abrufen:

• Die Mediendaten-Funktion der REST-API ist primär für den Abruf der zum einzelnen Produkt gehörenden Mediendateien gedacht und nicht zum Abruf größerer Cover- bzw. Mediendateien-Mengen wie z. B. Aufbau eines Mediendatenpools. Hierfür empfehlen wir Ihnen unsere Mediendatei-Feeds.

• Laden Sie bitte nur aktualisierte Mediendateien herunter. Sie können dafür auf verschiedenen Wegen einen Identifier für die aktuellste Version der Mediendatei oder das letztes Aktualisierungsdatum abrufen:
  • Option a) Im HTTP-Header schickt das VLB für GET-Requests den sogenannten ETag (Entity-Tag) als Identifier und das letzte Aktualisierungsdatum im Feld Last-Modified mit, die beide zum HTTP-Standard gehören. Das VLB empfiehlt, einen GET-Request mit der Bedingung If-None-Match oder If-Modified-Since zu implementieren, da Sie mit lediglich einem HTTP-Standard-Request zeitsparend prüfen, ob die Datei bereits bei Ihnen im System vorliegt und diese ggf. sogleich herunterladen.
    • If-None-Match: Diese Bedingung gleicht den gesendeten ETag-Wert mit dem ETag-Wert im VLB ab. Die angeforderte Mediendatei wird nur zurückgegeben, wenn die beiden Werte nicht übereinstimmen (Status 200). Wenn die beiden Werte übereinstimmen, Sie die Datei also bereits in der korrekten aktuellen Version haben, dann gibt der Server 304 (Not Modified) zurück.
    • If-Modified-Since: Ein Request mit dieser Bedingung gibt die angeforderte Mediendatei nur zurück, wenn das Datum in Last-Modified nach dem angegebenen Datum liegt (Status 200), andernfalls ist der Response 304 (Not Modified) ohne Body, d.h. ohne Mediendatei
  • Option b) Außerdem unterstützt das VLB sogenannte HEAD-Requests und gibt im HTTP-Header wie bei GET-Requests den ETag (Entity-Tag) und das letzte Aktualisierungsdatum im Feld Last-Modified an. Falls Sie in Ihrem Datenbestand für eine Mediendatei bereits dasselbe Update-Datum oder denselben ETag-Wert haben, brauchen Sie die Datei nicht erneut mit einem GET-Request herunterladen, da sich an der Datei nichts verändert hat.
    
  • Option c) Falls Sie die Produktdaten für eine Prüfung heranziehen möchten, gibt es in den Produktdaten für jede Mediendatei ein letztes Aktualisierungsdatum im JSON-Feld lastUpdated und den MD5-Hash-Wert im Feld JSON-Feld md5Hash, die Sie mit den Werten in Ihrem Datenstand abgleichen können.

• Benutzen Sie bitte Caching: Speichern Sie Mediendateien wie ein Cover nach einmaligem Download zwischen, damit das Cover nicht jedes Mal erneut über die REST-API abgerufen wird, wenn es z.B. nach einer Suchanfrage zur Anzeige in der Trefferliste benötigt wird.

Gelöschte Mediendateien

Wurde eine Mediendatei vom Verlag aus dem VLB entfernt, wird der Mediendateienlink nicht mehr über den REST-API-Aufruf der Liste der produktzugehörigen Mediendateienlinks im JSON-Format ausgeben. Wurde ein Titel beispielsweise an einem Tag mit einer Innenansicht im VLB angelegt, ist der Mediendateienlink über den REST-API-Aufruf verfügbar. Sollte der Verlag diese Innenansicht später aus dem VLB entfernen, ist der Mediendateilink anschließend nicht mehr in der Liste der produktzugehörigen Mediendateienlinks enthalten.