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:

• Markus Mächler markus.maechler@students.fhnw.ch
• Melanie Stucki melanie.stucki@students.fhnw.ch

Serie "Swissbib data goes linked"

Partie 1 | Partie 2 | Partie 3 | Partie 4

Dans ce quatrième et dernier article de la série sur le projet CUS P-2 linked.swissbib.ch, nous nous consacrons à l'API web pour clients informatiques. Le but de ce sous-projet est de mettre à disposition les structures de données liées à travers une interface REST, en diverses sérialisations RDF.

Figure 1: API REST comme interface pour les services de swissbib

L'API REST doit fournir une interface homogène vers l'extérieur, et rassembler à l'interne la possibilité de plusieurs services. L'infrastucture sous-jacente doit être transparente pour les clients de l'interface.

REST

REST (REpresentational State Transfer), un paradigme de programmation pour systèmes distribués, s'est imposé ces dernières années par rapport à d'autres approches (telles que SOAP), pour diverses raisons. REST est léger, extensible à de grandes quantités de données, facile à comprendre par les humain et également relativement simple à implémenter pour des clients de tout langage de programmation. Les bases d'un service REST sont, de manière simplifiée:

• Client-serveur
  Il existe une séparation nette entre client et serveur. Le client dirige les interactions et le serveur traite les requêtes et livre les données.
• Stateless
  Pour répondre, le serveur n'utilise que les données d'une seule requête HTTP, et ne se sert d'aucune autre information de contexte.
• Cacheable
  Le contenu d'une réponse du serveur doit être marquée de manière implicite ou explicite comme pouvant être stockée dans le cache ou pas.
• Layered system
  Les couches d'abstraction du systèmes global sont transparentes pour le serveur et pour le client.
• Uniform interface
• Chaque ressource (par exemple une ressource bibliographique) est accessible par une URL.
• Une ressource peut être comprise syntaxiquement et sémantiquement selon les données et métadonnées incluses dans la réponse. Ceci inclut entre autres l'indication du format (par exemple. JSON-LD) de la réponse.
• Quand un client interroge une ressource, il reçoit les informations suffisantes afin de pouvoir traiter ou supprimer (à condition qu'il en ait le droit) cette ressource.
• HATEOAS (Hypermedia as the Engine of Application State)

Cette dernière exigence (HATEOAS) est l'une des plus importantes et néanmoins le plus souvent négligée par beaucoup d'APIs REST. En bref, HATEOAS demande que l'API soit auto-descriptive. Cela signifie qu'un client informatique devrait être en mesure de comprendre, à partir d'un point d'entrée unique, quelles sont les actions possibles et les ressources à disposition à travers l'API. D'une perspective abstraite, un service REST conforme à HATEOAS représente un automate fini, dont les transitions d'états surviennent par la navigation au moyen des URLs mis à disposition.

Hydra (hypermedia-driven web APIs)

REST lui-même ne prescrit aucun standard sur la manière dont doit être construite une API auto-descriptive. C'est là qu'intervient Hydra, en tentant de standardiser le vocabulaire pour les APIs web hypermédia. Le Hydra Core Vocabulary, encore au stade de version préliminaire, est développé sous l'impulsion du collaborateur Google Markus Lanthaler et fait déjà preuve d'une grande popularité auprès de la communauté Linked Data. Le vocabulaire complet est déjà relativement vaste. Nous proposons ici deux exemples permettant d'illustrer le principe:

hydra:entrypoint
hydra:entrypoint est le point de départ de toute API. Toute la documentation ainsi que le point d'entrée lui-même sont au format JSON-LD. Le point d'entrée comprend tous les liens (liens relatifs pour l'instant encore) vers les ressources. Dans le cas de notre prototype, il s'agit avant tout des ressources bibliographiques (bibliographicResource). Le point d'entrée de notre prototype est accessible à l'URL suivante: http://sb-vf16.swissbib.unibas.ch/web/

Figure 2: hydra:entrypoint du prototype d'API REST de swissbib
(Pour les utilisateurs de Google Chrome, il est recommandé d'utiliser le plugin suivant: https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc)

hydra:collection
Une hydra:collection est une vue sur une quantité de ressources liées. Dans notre cas, ceci pourrait être une liste de ressources bibliographiques en tant que résultats d'une recherche. Etant donné qu'une telle quantité de ressources peut vite devenir très importante, le vocabulaire Hydra propose hydra: PartialCollectionView; cet élément décrit une vue d'un sous-ensemble des objets d'une collection. Il peut contenir des liens (hydra:first, hydra:last, hydra:next et hydra:previous) afin de pouvoir atteindre tous les éléments de la vue. Les ressources elles-mêmes se trouvent dans le champs "hydra:member". L'URL suivante propose un exemple d'une telle requête: http://sb-vf16.swissbib.unibas.ch/web/bibliographic_resources?dct:title=linked%20data

Figure 3: L'affichage d'une hydra:collection dans le prototype d'API REST de swissbib

Cette standardisation au moyen du vocabulaire Hydra permet dès lors d'écrire un client générique, qui peut lister les interactions possibles avec l'API web. Markus Lanthaler a déjà développé un tel client générique pour explorer l'API: http://www.markus-lanthaler.com/hydra/console/ (URL: http://sb-vf16.swissbib.unibas.ch/web).

Prototype

Après avoir vu les premiers résultats du prototype, nous souhaitons encore abordé l'aspect de son implémentation. Le développer Markus Lanthaler a créé une première implémentation Hydra de référence, SymfonyBundle, dans le langage de programmation PHP. Sur cette base ont émergé de nouveaux développements en lien avec Hydra, entre autres le framework APIPlatform. Ce dernier a été lancé pour la première fois en juin 2015, en version 1, et la prochaine version majeure 2.0 est sur le point d'être publiée. Le framework propose une bonne prise en charge de Hydra, avec notamment la possibilité de relier entre elles des sources de données relativement simples (DataProvider) ainsi que de sérialiser divers formats de sortie (à travers Responder). Dans notre prototype, nous avons implémenté notre propre DataProvider, simple, qui charge les données liées au format JSON-LD depuis un serveur Elasticsearch. Avec des classes Responder que nous avons développées, les données peuvent - selon les requêtes du client - être sérialisées et diffusées dans d'autres formats RDF. Le graphique ci-dessous illustre ce processus.

Le code source de ce prototype peut être consulté sur Github: https://github.com/linked-swissbib/hydra-swissbib.ch/tree/prototype_v2

Synthèse

Nous sommes persuadés d'avoir trouvé avec Hydra un vocabulaire pour les APIs web hypermédias qui conviendra parfaitement à nos données liées. La plateforme de framework API nous a convaincus et, dans les prochaines semaines, nous travaillerons activement sur le développement de l'API sur la base de ce prototype. L'état actuel du développement peut être suivi sur Github: https://github.com/linked-swissbib/hydra-swissbib.ch

Auteurs du texte:

• Markus Mächler markus.maechler@students.fhnw.ch
• Melanie Stucki melanie.stucki@students.fhnw.ch