Donnerstag, 21. Juli 2016

Swissbib data goes linked Teil 4: Hydra Web API for smarter clients

Deutsche Version Version française

Serie "Swissbib data goes linked"
Teil 1 | Teil 2 | Teil 3 | Teil 4

Im vierten und letzten Teil der Artikelserie zum SUK P-2-Projekt linked.swissbib.ch möchten wir uns der Web API für maschinelle Clients widmen. Ziel dieses Teilprojektes ist es, die verlinkten Datenstrukturen über eine REST Schnittstelle in verschiedenen RDF Formaten zur Verfügung zu stellen.

Illustration 1: REST API als Schnittstelle für swissbib Services

Die REST API soll dabei eine einheitliche Schnittstelle nach aussen anbieten und gegen innen die Möglichkeit verschiedene Dienste anzubinden. Für Clients der Schnittstelle soll die dahinterliegende Infrastruktur transparent sein.

REST

REST (REpresentational State Transfer), ein Programmierparadigma für verteilte Systeme, hat sich in den letzten Jahren gegenüber anderen Ansätzen (z.B. SOAP) aus verschiedenen Gründen durchgesetzt. REST ist leichtgewichtig, skalierbar, einfach verständlich für Menschen und auch relativ einfach zu implementieren für Clients in jeglichen Programmiersprachen. Die Grundsätze eines REST Service sind vereinfacht:
  • Client – Server
    Es gibt eine klare Trennung zwischen Client und Server. Der Client steuert die Interaktionen und der Server verarbeitet Daten oder liefert diese aus.
  • Stateless
    Der Server benutzt nur Daten aus einem einzelnen HTTP Request um die Anfrage zu beantworten und nutzt keine weiteren Kontextinformationen.
  • Cacheable
    Der Inhalt einer Server-Antwort muss implizit oder explizit als cachebar oder nicht cachebar gekennzeichnet sein.
  • Layered System
    Für Server und Client ist transparent ob das Gesamtsystem aus mehreren Abstraktionsschichten besteht oder nicht.
  • Uniform interface
    • Jede Ressource (z.B. eine bibliographische Ressource) ist über eine URL ansprechbar.
    • Eine Ressource kann syntaktisch und semantisch verstanden werden anhand der enthaltenen Daten und Metadaten aus einer Antwort. Das beinhaltet unter anderem die Information in welchem Format (z.B. JSON-LD) die Antwort ist.
    • Wenn ein Client eine Ressource abgefragt hat, hat er damit genug Informationen um die Ressource zu bearbeiten oder zu löschen (vorausgesetzt er hat das Recht dazu).
    • HATEOAS (Hypermedia as the Engine of Application State)
Diese letzte Anforderung (HATEOAS) ist eine der wichtigsten und doch am meisten vernachlässigte bei vielen REST APIs. Kurz gesagt besagt HATEOAS, dass die API selbstbeschreibend sein muss. Das heisst ein maschineller Client sollte über einen einzigen Einstiegspunkt in der Lage sein zu verstehen welche Aktionen auf welchen Ressourcen über die API ausgeführt werden können. Abstrakt betrachtet stellt ein HATEOAS-konformer REST-Service einen endlichen Automaten dar, dessen Zustandsveränderungen durch die Navigation mittels der bereitgestellten URLs erfolgen.

Hydra (hypermedia-driven web APIs)

REST selbst schreibt keinen Standard vor, wie eine selbstbeschreibende API aufgebaut sein soll. Genau an diesem Punkt setzt Hydra an mit dem Versuch das Vokabular für Hypermedia-getriebene Web APIs zu standardisieren. Das Hydra Core Vocabulary ist noch ein inoffizieller Entwurf, der von Google Mitarbeiter Markus Lanthaler vorangetrieben wird und sich besonders im Linked Data Umfeld bereits grosser Beliebtheit erfreut. Das gesamte Vokabular ist schon relativ umfangreich. Um das Prinzip zu veranschaulichen möchten wir hier deshalb nur zwei Beispiele betrachten.

hydra:entrypoint
Der Hydra:Entrypoint ist der Startpunkt jeder API. Der Entrypoint selbst, sowie die gesamte API Dokumentation, ist im Format JSON-LD. Im Entrypoint enthalten sind alle weiterführenden Links (zur Zeit noch relative Links) zu den Ressourcen. Im Falle unseres Prototyps sind dies erst die bibliographischen Ressourcen (bibliographicResource). Der Entrypoint unseres Prototyps ist unter folgender URL zu finden: http://sb-vf16.swissbib.unibas.ch/web/

Illustration 2: hydra:entrypoint des swissbib REST API Prototyps
(Für Google Chrome Benutzer empfiehlt sich folgendes Plugin: https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc)

hydra:collection
Eine Hydra:Collection ist die Sicht auf eine Menge von zusammenhängenden Ressourcen. In unserem Fall könnte das eine Liste der Suchresultate für bibliographische Ressourcen sein. Da eine solche Menge von Ressourcen sehr schnell sehr gross werden kann gibt es im Hydra Vocabulary die Hydra:PartialCollectionView. Diese beschreibt eine Sicht auf eine Untermenge aller Elemente einer Collection. In einer Hydra:PartialCollectionView können Links (hydra:first, hydra:last, hydra:next und hydra:previous) enthalten sein um alle Elemente dieser Sicht abzufragen. Die Ressourcen selbst befinden sich im Feld "hydra:member". Ein Beispiel für eine solche Abfrage findet sich unter folgender URL: http://sb-vf16.swissbib.unibas.ch/web/bibliographic_resources?dct:title=linked%20data

Illustration 3: Die Ausgabe einer hydra:collection des swissbib REST API Prototyps

Diese Standardisierung mittels des Hydra Core Vocabulary erlaubt es nun einen generischen Client zu schreiben, der die möglichen Interaktionen mit der Web API auflisten kann. Einen solchen generischen Client zum Entdecken der API hat Markus Lanthaler bereits entwickelt: http://www.markus-lanthaler.com/hydra/console/ (URL: http://sb-vf16.swissbib.unibas.ch/web)

Prototyp

Nachdem wir bereits die ersten Resultate des Prototyps gesehen haben, möchten wir noch etwas auf dessen Implementierung eingehen. Eine erste Hydra Referenzimplementierung wurde von Hydra Schöpfer Markus Lanthaler als SymfonyBundle in der Programmiersprache PHP entwickelt. Daraus entstanden vor allem in diesem Umfeld weitere Entwicklungen im Zusammenhang mit Hydra. Unter anderem entstand das Framework APIPlatform. Das Framework wurde zum ersten Mal im Juni 2015 in Version 1 veröffentlicht und steht kurz vor seinem Release in der nächsten Major Version 2.0. Das Framework bietet umfangreiche Hydra Unterstützung. Innerhalb dessen ermöglicht es relativ einfach eigene Datenquellen (DataProvider) anzubinden sowie weitere Serialisierungsformate (über Responder) in der Ausgabe anzubieten. In unserem Prototypen haben wir einen eigenen einfachen DataProvider implementiert, der die verlinkten Daten im Format JSON-LD aus einem Elasticsearch Server lädt. Mit eigens implementierten Responder-Klassen lassen sich dann je nach Anfrage des Clients die Daten in andere RDF Format serialisieren und ausgeben. Die folgende Grafik stellt eine vereinfachte Darstellung des Prozesses dar:


Der Code des Prototyps ist auf Github einsehbar: https://github.com/linked-swissbib/hydra-swissbib.ch/tree/prototype_v2

Fazit

Wir sind überzeugt mit Hydra ein Vokabular für Hypermedia-getriebene Web APIs gefunden zu haben, dass optimal zu unseren verlinkten Daten passt. Mit der Entwicklung des Prototyps konnten wir uns vom Framework API Platform überzeugen und werden In den nächsten Wochen auf Basis des Prototyps die Entwicklung der REST API vorantreiben. Der Aktuelle Stand der Entwicklung kann auf Github verfolgt werden: https://github.com/linked-swissbib/hydra-swissbib.ch

AutorInnen des Beitrags:

Kommentare:

Unknown hat gesagt…

Sehr interessante Artikelserie. Vielen Dank fürs Schreiben und Veröffentlichen. Eike Kleiner

markus-lanthaler.com hat gesagt…

Vielen Dank für diesen Blogpost, ich hatte keine Ahnung dass Hydra in diesem Projekt zum Einsatz kommt :-)

Kommentar veröffentlichen