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 RDFFormaten 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:

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:

Weiterlesen

Considerations for the development of an infrastructure to enable the project linked.swissbib.ch (part 1)


The proposal “linked.swissbib.ch” was accepted by SUC P2 – („Scientific information: access, processing and safeguarding“) as one of the projects for building the future infrastructure to access scientific digital information.

The application was submitted by Haute école spécialisée de Suisse occidentale HES-SO -Haute Ecole de Gestion, Genève in cooperation with HTW Chur and Universitätsbibliothek Basel (project swissbib).

One of the aims of the project is the transformation of the current swissbib content into a Semantic Data format (RDF) to enable and simplify the linking of swissbib data with external information.

Finally the created services by linked.swissbib.ch should run on the infrastructure provided by swissbib.ch to facilitate scientists and general library users access to the linked information. Additionally the infrastructure should be available and usable for any other project or service who wants to work on similar questions (catchphrase: “swissbib as a working bench”)

This first blog contribution reflects my current considerations and experiments for the selected tools part of the future infrastructure. Of course this is a work in progress. Contributions and suggestions are always welcomed.

I. General requirements for future tools and the infrastructure to be created by linked.swissbib.ch (and swissbib classic)

a) The software has to transform any kind of meta-data structure into another (meta-data) structure.

b) In general the chosen software should be reusable and expandable. The used development tools should be state of the art and future-proof (if this is at all possible in the software world…)

c) The software has to be Open Source – otherwise it is often difficult or nearly impossible for other parties or services to (re)-use it.

d) The software shouldn’t be in a phase of its infancy. Because of our really restricted resources we can’t afford to build a new software just from scratch. It should be demonstrated that it is already used by institutions in a similar way that we intend to use it with linked.swissbib.ch.

e) Ideally there should exist a community around the system which enables further development in the future.

f) The software for meta-data transformation should be usable not only by software developers.
People related to meta-data transformations in the library world (scripting knowledge is helpful but not necessary) should be able to define work-flows for their own purposes – recently I heard that the phrase “biblio information scientist” is sometimes used as an expression for such a group of people.

g) The software tools should be very scalable.

The mechanisms should be available on a desktop (for example a person in development of a workflow for metadata transformations) and at the same time it should be possible to use the same artifact on a cluster to process millions of items in reasonable time. Actually the classic swissbib content consists of around 20 million records (merged). We are in charge to include licensed article meta-data in the swissbib data-hub. This content (potentially between 30 -150 million descriptions) should also be transformed and serialized into a semantic RDF format.

II. Possible software alternatives to reach the defined goals


A. Infrastructure developed by the Culturegraph project (German National library)
 

One of the main components provided by Culturegraph is called MetaFacture which in turn comprises of three main parts: Framework, Morph and Flux. You can find a more detailed explanation of these parts on the Wiki of the software on Github .

To get to know and to evaluate the component I created my own repository on Github. There I included the sources of the lobid project

1) How are the main components of Culturegraph related to the general requirements defined above?

a) Framework:

The framework makes the solution re-usable and expandable. It defines general classes and interfaces which could be used by others (swissbib too) to extend the solution in a way it is required for their aims.

As an example for this: The metafacture-core component provides commands which are combined to FLUX – workflows (we will see the description of this later). These commands were extended by HBZ by some commands of their own to serve their needs.

Beside new commands being part of the workflow you can define new types as functions being part of the Metamorph domain specific language.

The same mechanism to write specialized functionality with dedicated commands beside the metafacture-core commands is used by the Culturegraph project itself. There already exist connectors for SQL databases, NoSQL stores like the often used Mongo store and to include Mediawiki content as part of the meta-data transformations.  All these repositories are available on Github

b) (Meta)-Morph transformation language

Morph is a Domain Specific Language to define Meta-Data transformations using XML. Hereyou can find a larger example for a morph script which was build by HBZ to transform bibliographic MAB descriptions into RDF. For the result of this transformation (done by myself with the evaluation repository on Github)  look here

My guess (at the moment – I’m still in the phase of evaluation): Metamorph enables you to define at least most of the transformation required for our needs.
For most of the work,knowledge of programming languages isn’t necessary. You have to know your meta-data structures and how you want to transform it.

General potential of Meta-Morph:
In the mid-term perspective I have in mind to use this kind of solution not only for transformations into RDF but for already existing processes in the classic swissbib service too (CBS FCV transformations and Search Engine – SOLR / Elasticsearch – document processing for example)

c) FLUX – create workflows for transformation processes

I would describe FLUX as a “macro language” (similar to macros in office programs) for the definition of processing pipelines.Here you can find an example.

The following picture will give you an overview and idea how heterogeneous article meta-data (provided by publishers) could be normalized in processes based on Metafacture.

 

To support the creation of FLUX work-flows (especially for non developers) HBZ implemented an Eclipse extension. This extension gives you suggestions for commands (together with their arguments) as part of whole work-flows. Additionally you can start a FLUX process under control of the extension. Fabian Steeg (HBZ and creator of the extension) wrote a helpful summary of the
metafacture-ide and metafacture-core out of his point of view.

2) Additional relations to the defined goals

As I tried to describe: the main parts of Metafacture (and extended components based on the core framework) addresses the requirements of the goals in a), b) and f)
(meta-data transformation / reusable, expandable and future proofed / not only for software developers)

But what about the other defined goals:

– The software is Open Source, originally developed by the Deutsche Nationalbibliothek and available via Github and Maven

– The software (Metafacture) isn’t in itsphase of infancy and a community has been established around it. Currentlydeployed as version 2.0,it is the heart of the linked data service provided by DNB. It is already re-used by other institutions for their services (especially HBZ for lobid.org serviceand SLUB Dresden for their EU financed “Data Management Platform for the Automatic Linking of Library Data„)

– The infrastructure should have the potential being very scalable.
Transformation processes of meta-data are currently often based on traditional techniques like relational databaseswhich is proven and mature. E.g. a lot of sophisticated meta-data transformation processes were created by swissbib classic in the last 5 years.
We don’t have in mind to throw away
thesepossibilities and collected experiences in the past. And even for the remarkable larger amount of meta-data for licensed articles we think it makes sense and it is possible to use it by increasing our (virtual) hardware.
But (probably soon) there comes the point in time where newer possibilities should be used (at least in parallel). These possibilities are often labeled with the catchphrase “Big Data” and behind these catchphrases are mostly Hadoop for distributed processing and distributed (NoSQL) storages like Hbase.

Because the Metafacture work-flows are stream-based (combining several modules in a chain) it is well prepared to run on a Hadoop Cluster. Culturegraph has already done this with their component called metafacture-cluster.
This technique made it possible for them to bring together all the bibliographic resources of all the library networks in Germany and to build clusters of equal or similar data (which is a foundation of their Linked Data service) – really fast. This is actually done by swissbib classic within our current data-hub based on traditional technologies (see above). Here you can find a more detailed view on the architecture of the current swissbib.
We have to keep this aspect (processing of really large amounts of data) in mind. Perhaps not immediately when it comes to article data but with greater probability if research data should be incorporated into a data-hub like swissbib.

B. Toolset developed by LibreCat (with Catmandu as the Backbone)



I don’t have any experience with LibreCat.

I spoke with a colleague (who is involved in the community) about the current status of the project and we tried to compare it on a very high level.

One sentence I still have in my mind:
Because Culturegraph is based on Java they (Culturegraph) use a lot of XML while Librecat (implemented in Perl) can do the same pretty much faster directly in the code.

 
I guess it’s true as long asit’s true… there are some misconceptions from my point of view:

a) There is no use of XML because the core of Metafacture is implemented in Java. Java and XML aren’t correlated in any way. Metafacture uses XML because it’s the mean (not more) to express the DSL (Domain Specific Language – Metamorph) used to define meta-data transformations. This makes it possible for people without advancedprogramming skills to define such transformations on a higher level.

b) a clear separation of implementation and definitions for meta-data transformations (the rules) is not unimportant to make the system in the long term better maintainable although it’s probably faster and easier to understand ‚for the developer itself‘ to implement transformations in Perl.
– maybe a very subjective point of view:
Today I wouldn’t implement a system with Perl. If a dynamic scripting language my recommendation would be something like Python or Ruby. Although things change pretty fast nowadays my impression is that Perl isn’t often used by younger people. It might be different in the ‚current‘ library world. But my assumption is it’s going to change in the future.
– Especially when it comes to the processing of large amounts of data – I wouldn’t use dynamic scripting languages. Execution performance is one thing. The other: the integration with clusters for large amounts of data is less supported.

Nevertheless: we should keep an eye on the development in the project. A noticeable group of people (able to contribute) is interested in the project and as I tried to depict it in my picture above:
I guess we could integrate it (if reasonable) in an infrastructure like Metafacture.

Another aspect: If it is possible to re-use the work for normalization of licensed article meta-data done by GBV we have to be “Java compatible”. If I’m not wrong the work is done on the basis of this programming language.

Weiterlesen