VLB Rest Client ist eine einfache, leicht verständliche Klassenbibliothek (.dll) für .NET 4.5, die einen schnellen und unkomplizierten Zugriff auf die REST-Api des VLB ermöglicht. Der Nutzer muss sich nun nicht mehr mit den Details der Api-Spezifikation oder der REST-Technologie auseinander setzen, dies wird alles von VLB Rest Client übernommen - Sie können sich somit einzig auf ihr Projekt konzentrieren!

 

Features:

- Schneller Zugriff auf die vlb.de REST-Api. Es werden keine Kenntnisse der REST-Technologie oder Details der Api-Spezifikation benötigt. Grundlegende Programmierkenntnisse, eine Internetverbindung und vlb.de-Zugangsdaten (Account/Passwort oder Tokens) sind ausreichend.

- Login / Logout mit ihren vlb.de-Zugangsdaten über die vlb.de REST-Api.

- Suchen und Sortieren von Produkten.

- Abrufen von Metadaten.

- Download von Covern und Mediendaten.

- Indexsuche in allen verfügbaren Indices.

- Speichern der abgerufenen Daten in logisch aufgebauten und schnell verständlichen Datenstrukturen.

- Kodierung vieler Parameter in Enumerationen, was zu einer Reduktion möglicher Fehlerquellen führt.

 

Features to come:

- Mit dem 01.01.2016 müssen Bundles, bzw. deren Teilprodukte nach Aussage des Bundesfinanzministeriums (BMF) getrennt besteuert und folglich deren MwSt-Sätze separat angegeben werden. Die VLB Rest-Api unterstützt dies bereits, der VLB Rest Client muss hier noch nachlegen. Mehr Informationen hierzu finden Sie unter: http://info.vlb.de/files/bundle_preisauszeichnung_rest.pdf

 

Verwendung:

VLB Rest Client kann in .NET 4.5 Projekten verwendet werden. Importieren Sie hierfür die VLB_RestClient.dll mittels eines Verweises in ihr Projekt (eine Anleitung hierzu finden sie hier für Visual Studio und hier für MonoDevelopment / Xamarin). Anschließend können Sie den ersten REST-Request senden.

 

Login:

Sollten Sie einen vlb.de Account und Passwort besitzen, müssen Sie sich zunächst anmelden und einen temporär gültigen Token erzeugen (dies gilt nicht für Nutzer der stateless-Tokens, die permanent gültig sind. Diese Nutzer überspringen bitte den Login-Teil):

 

RestRequest restClient = new RestRequest();

string accessToken = restClient.login("meinAccount", "meinPasswort");

 

Mit diesem Token erhalten Sie Zugriff auf alle anderen Funktionen der Api. Bitte bedenken Sie, dass der Token nach längerer Inaktivität (ca. 60 Minuten) automatisch seine Gültigkeit verliert. Nach getaner Arbeit sollten Sie immer ihren Token und damit ihren Account durch einen Logout-Request freigeben, dazu später mehr.

 

Suche:

Nun können Sie ihre erste Suche durchführen. Ein Beispiel:

 

JsonDataContainerSearch jsonDataContainerSearch = restClient.search(accessToken, "Ein schönes Buch", 1, 25, RestRequest.sortField.isbn, RestRequest.sortSequence.desc, RestRequest.source.VLB);

 

Dieses Beispiel zeigt eine Standardsuche. Zunächst muss, wie bei nahezu jedem Methodenaufruf, zunächst der beim Login erzeugte Token zur Authentifizierung des Nutzers übergeben werden. Anschließend folgt der Suchbegriff. In diesem Fall wird eine Schnellsuche nach "Ein schönes Buch" durchgeführt. Die Suche kann jedoch mittels boolescher Suchparameter deutlich verfeinert werden - dies hier zu erläutern würde den Umfang des Tutorials sprengen, bitte schlagen Sie für Details zur booleschen Suche in der vlb.de REST-Api-Spezifikation nach. Ein Beispiel für eine solche boolesche Suche wäre "TI=Windows UND AU=Meier".

Anschließend folgen einige optionale Parameter. Die Suchergebnisse werden in "Seiten" präsentiert, d.h. immer nur eine spezifische Anzahl an gefundenen Titeln (in diesem Fall 25) werden gleichzeitig angezeigt, um die benötigte Bandbreite möglichst gering zu halten. In diesem Beispiel wird Seite 1 angezeigt, die 25 Titel enthält. Welche Titel auf dieser Seite angezeigt werden, ist abhängig von der Sortierung. In diesem Beispiel wird über die Enumeration sortField festgelegt, dass nach der ISBN sortiert wird. Die Enumeration sortSequence legt fest, in welcher Reihenfolge (aufsteigend oder absteigend) sortiert wird. Der letzte Parameter gibt an, welche Datenbank durchsucht wird. In den allermeisten Fällen ist dies das VLB (Verzeichnis lieferbarer Bücher), doch stehen auch SBZ (Schweizer Buchzentrum) und OESB (Österreichisches Schulbuchzentrum) zur Verfügung.

Der Rückgabewert der Methode ist ein JsonDataContainer - ein von der DLL zur Speicherung nahezu aller Rückgabewerte der Api verwendete Datenstruktur. Diese enthält alle Felder, die in diesem Fall von der Suchanfrage geliefert werden, stets im string-Format. Composites, d.h. eine oftmals mehrfach vorkommende Sammlung von Feldern, werden in eigenen Subcontainer gespeichert. Ein JsonDataContainer bildet immer exakt die Struktur der Json-Response der REST-Api ab, d.h. Sie können über die Beispiele der vlb.de REST-Api-Spezifikation leicht lernen, wie ein JsonDataContainer aufgebaut ist - oder alternativ einfach ein wenig herumforschen.

 

Detailansicht:

Bislang haben Sie erst eine Suche durchgeführt - mit Hilfe des erhaltenen JsonDataContainerSearch-Objektes können Sie nun die Detailansicht einzelner Titel aufrufen:

 

JsonDataContainerDetail jsonDataContainerDetail = restClient.getTitleDetailData(accessToken, jsonDataContainerSearch.content[0].isbn);

 

Ein Titeldetailaufruf benötigt neben dem Token lediglich eine ISBN, die sich leicht aus dem JsonDataContainerSearch-Objektes auslesen lässt. In diesem Fall wird die ISBN vom obersten Produkt der Suchanfrage verwendet und die Antwort des Servers wiederum in einem JsonDataContainer gespeichert. Natürlich kann auch einfach eine ISBN als string übergeben werden, z.B. "978-3-12345-6789". Im Folgenden werden exemplarisch die Titel eines Produktes und alle verfügbaren Preise mit Währungen ausgegeben:

 

for(int i = 0; i < jsonDataContainerDetail.titles.Length; i++)

{

    Console.WriteLine(jsonDataContainerDetail.titles[i].title);

}

 

 for (int i = 0; i < jsonDataContainerDetail.prices.Length; i++)

{

    Console.WriteLine(jsonDataContainerDetail.prices[i].value + " " + jsonDataContainerDetail.prices[i].currency);

}

 

Weitere Requests:

Alle übrigen Requests verhalten sich identisch zum oben gezeigten Ablauf - daher sollen sie an dieser Stelle nur mit wenig Kommentar aufgelistet werden:

 

Abruf von Verlagsinformationen über die MVB-Kennummer des Verlags:

 

JsonDataContainerPublisher jsonDataContainerPublisher = restClient.getPublisherData(accessToken, jsonDataContainerDetail.publishers[0].publisherId);

 

Abruf von Mediendateien-URLs über die ProduktId eines Produkts:

 

JsonDataContainerMedia[] jsonDataContainerMedia = restClient.getMediaData(accessToken, jsonDataContainerDetail.id);

 

Abruf eines Covers in Form einer jpg-Datei. In diesem Beispiel wird die Datei zudem auf der Festplatte gespeichert:

 

Image coverImage = restClient.downloadCover(accessToken, jsonDataContainerSearch.content[0].isbn);

coverImage.Save(jsonDataContainerSearch.content[0].isbn + ".jpg");

 

Ein wenig komplexer ist der Abruf von Mediendateien, die in unterschiedlichen Formaten existieren und daher als Stream ausgegeben werden. Hierfür muss beim Aufruf der entsprechenden Methode ein Stream übergeben werden, in den der Datenstrom geleitet wird. Die Rückgabe der Methode definiert das Dateiformat der herundergeladenen Mediendatei als string. In diesem Beispiel wird eine Mediendatei heruntergeladen und auf dem lokalen Verzeichnis im korrekten Dateiformat gespeichert.

 

Stream memoryStream = new MemoryStream();

string fileFormat = restClient.downloadMedia(accessToken, jsonDataContainerMedia[0], ref memoryStream);

FileStream fileStream = File.Create("meineMediendatei." + fileFormat);

((MemoryStream)memoryStream).WriteTo(fileStream);

memoryStream.Flush();

memoryStream.Close();

fileStream.Flush();

fileStream.Close();

 

Logout:

Thats it! Als letztes bleibt nur noch, sich auszuloggen und den Token und damit den Account wieder freizugeben. Nutzer der permanent gültigen stateless-Tokens können diesen Schritt natürlich auslassen.

 

restClient.logout(accessToken);

 

 

 

Voraussetzungen:
Die Programmbibliothek benötigt .NET 4.5 oder höher (Windows 7 und höher hat .NET 4.5 bereits vorinstalliert). Eigene VLB-Zugangsdaten werden für die Nutzung vorausgesetzt.

 

Installation:

Laden sie die .zip Datei herunter und entpacken Sie sie in einem beliebigen Verzeichnis. Anschließend folgen Sie den im Kapitel "Verwendung" angegebenen Anweisungen zum Import in ihr Projekt.

 

Changelog:

Version 1.1:

- Zusätzliche Felder zur Sortierung der Suchergebnisse wurden hinzugefügt.

- Suchanfragen erlauben nun die Filterung von aktiven und inaktiven Titeln.

- Implementierung der ISBN-Stapelsuche.

- downloadMedia gibt das Format von als .zip-Datei gepackten Epubs nun korrekt aus.

- Der Endpoint kann nun vom Nutzer editiert werden. Dadurch kann die angesteuerte URL angepasst werden, was beispielsweise die Nutzung des vlb.de-Testsystems ermöglicht.

 

Quellen / Inhalte:
Das Programm wurde mit Visual Studio Community 2015 und .NET 4.5 (C#) erstellt.

JSON Net

Rest Client