subobject / adress

[guenterh]

• branch https://github.com/linked-swissbib/hydra-swissbib.ch/tree/api.2.3_subresource
• angepasste Entitäten (Ressourcen) :
  https://github.com/linked-swissbib/hydra-swissbib.ch/blob/api.2.3_subresource/src/Entity/Address.php https://github.com/linked-swissbib/hydra-swissbib.ch/blob/api.2.3_subresource/src/Entity/Organisation.php
  https://github.com/linked-swissbib/hydra-swissbib.ch/blob/api.2.3_subresource/config/api_platform/resources.yaml

Das Ziel: ich möchte Adressen von Organisationen als eigenes Objekt anzeigen können (denke zumindest, dass es ein sinnvoller Weg ist, dies über ein Objekt (Entität) zu machen und dafür den Mechanismus von subobjects zu verwenden.
Beispiel im Index: http://[server]/organisation/ABN-KH

Definition über Annotationen als API-Resource
/**
 * An Address
 *@see https://www.w3.org/2006/vcard/ns#
 * @ApiResource(
 *          subresourceOperations={
 *          "organization_get_subresource"={
 *              "method"="GET",
 *              "path"="/organisation/{id}"
 *          },
 *      },
 * )
 *
 *
 * @author   Günter Hipler <guenter.hipler@unibas.ch>>
 * @license  http://opensource.org/licenses/gpl-2.0.php
 * @link     http://linked.swissbib.ch

Dies funktioniert, das Objekt wird gefunden, ich bekomme jedoch ein Router Problem. Die Komponente twigs kann nicht die id doppelt anzeigen.
Zwei Dinge gehen mir durch den Kopf:

• Das Adressen Objekt müsste gar keine id haben
• warum wird die twigs Komponente überhaupt mit einbezogen auch wenn ich zum Beispiel json-ld -Serialisierung anfordere.

beschreibe ich dies mit Hilfe eines yaml-Ressourcenfiles (config/api-platform/resources.yaml)
dann bekomme ich die Fehlermeldung, dass die Ressource nicht gefunden werden kann. Habe bisher noch keinen Weg gefunden, dies abzustellen.

Setze ich die Annotation in die property des Objekts, erhalte ich den Fehler, dass die Annotation nicht gefunden werden kann. Ich stehe damit wohl noch auf Kriegsfuss...

    /**
     * @var Address
     * @ApiSubresource()
     */
    private $address;

Für mich das Ziel dieses tasks

• das Projekt ist nach dem Wechsel zu Symphony4 wieder “aufgeräumt”. Ich habe den Eindruck, dass ich zwar einiges machen konnte, weil mir aber das tiefergehende Verständnis noch fehlt, so manches noch nicht korrekt ist

• wir können diskutieren, ob subressources der richtige Weg zur Abbildung von Relationen ist

• vielleicht können wir (ich) bereits eine Lösung aufgrund der Diskussion implementieren/andenken. Vorher sollten wir, wie abgemacht, jedoch darüber diskutieren, wie solche Strukturen über unseren dataProvider zur Verfügung gestellt werden können

• Ich verstehe die “magic” - Zusammenhänge von Symphony4 (und zum Teil von api-platform ) besser. Davon verspreche ich mir, besser über unsere eigentlichen Ziele nachdenken zu können.

[guenterh]

Ein paar Detailfragen

• Wo find ich die Definitionen dazu, welche Attribute ich in Annotationen verwenden darf
  Hier https://api-platform.com/docs/core/operations#configuring-operations werden viele genannt. Ich würde erwarten, dass sie im Namespace ApiPlatform\Core\Annotation der API-Platform definiert werden. Dort sehe ich das aber nicht (Ich habe nach dem Attrubut requirements gesucht, was in dem Beispiel genannt wird). Habe ich die PHP Annotationen noch nicht richtig verstanden.
  Bisher glaube ich verstanden zu haben, dass ich die ganze Vielfelt der Beschreibungen in yaml-files besser abbilden kann (Meine subobjects)

[maechler]

Hallo Günter

Ich habe mir erlaubt einige Dinge gleich im Code zu beheben und hinzuzufügen, da ich selber etwas testen musste wie das umzusetzen ist. Nachfolgend versuche ich deine Fragen zu beantworten und zu erklären, was ich gemacht habe.

Router Problem
So wie ich das sehe, wird Twig zuerst einmal nicht verwendet, wenn die JSON-LD Serialisierung angefragt wird. Der Fehler stammt eigentlich vom Router, der die URL nicht sinnvoll auflösen kann, da zweimal der Parameter {id} vorkommt. Aufgrund dieses Fehlers wird versucht eine Fehlerseite mit Twig-Templates anzuzeigen, da scheint der selbe Fehler aber nochmals eine Exception zu verursachen. Deshalb kommt bei jeder Serialisierung schlussendlich ein Twig_Error_Runtime.

Ich habe daraufhin einfach mal im ganzen Projekt nach {id} gesucht und bin darauf gestossen, dass diese im CamelCaseResourcePathGenerator vorkommt. Der PathGenerator wird dazu verwendet einen Ressourcen-Namen in ein URL-Pfadsegment zu transformieren. Als ich unseren eigenen PathGenerator mit dem der ApiPlatform verglich, ist mir aufgefallen, dass dort keine {id} mehr verwendet wird. Das wird neuerdings ausserhalb des PathGenerator vom Framework übernommen.
Daraufhin habe ich den CamelCaseResourcePathGenerator angepasst, siehe: 3c2ab3b

Annotationen
Der Fehler, dass die Annotation nicht gefunden werden kann, stammt von einem Tippfehler im Namespace. Es sollte ApiPlatform anstelle von APIPlatform sein, siehe: 2861c10

Du siehst das absolut richtig, die Annotationen, die du verwenden kannst, findest du unter ApiPlatform\Core\Annotation . Die Klassen, die dort definiert sind, kannst du mit @Klassenname() verwenden. Das sind meines Wissens alle Annotation, die API Platform zur Verfügung stellt.

Die Eigenschaft requirements, die du erwähnst, ist ein untergeordnetes Element des Attributes itemOperations. Das Attribut itemOperations ist als beliebiger Array definiert (https://github.com/api-platform/core/blob/1f11969cd452b2a61cdbf36e93f1ddbe5478e9e1/src/Annotation/ApiResource.php#L40), das heisst es kann beliebige key => value Paare, wie z.B. requirements => ??? enthalten.

Die oberste Ebene der möglichen Attribute einer Annotation sind innerhalb der Klasse mit @Attributes definiert. Auf der ersten Ebene der Attribute einer Annotation hört das Schema aber bereits auf. Welche spezifischen Attribute es innerhalb des Arrays itemOperations gibt, kann meines Wissens nur noch über die Dokumentation (https://api-platform.com/docs/core/operations) oder direkt im Code nachvollzogen werden.
Das angegebene XML Schema der Konfiguration geht leider auch nicht tiefer: https://github.com/api-platform/core/blob/master/src/Metadata/schema/metadata.xsd

Wenn ich im Code nach requirements Suche, dann stosse ich auf folgende Stelle: https://github.com/api-platform/core/blob/b4e5c213f5c10dac2fe05beff75464f06d0a6570/src/Bridge/Symfony/Routing/ApiLoader.php#L205-L219
Die Parameter werden mehr oder weniger einfach so an die Symfony Klasse Route durchgereicht. Die Dokumentation dazu findest du hier: https://symfony.com/doc/current/routing.html#adding-wildcard-requirements

Subresources
Ja, ich denke auch, dass Subresources der richtige Weg sind um die Adressen abzubilden. Damit das funktioniert, muss ein SubresourceDataProvider implementiert werden. Ich habe dazu leider nichts in der Dokumentation gefunden, es zeigt sich wiedereinmal, dass die Dokumentation vorallem für den Standard-Fall gut ist, bei dem einfach eine Datenbank verwendet wird. Ich musste das direkt aus dem Code herausfinden.

Ich habe jetzt mal einen ElasticsearchSubresourceDataProvider implementiert, der einfach immer dieselbe Adresse ausgibt, siehe: 162a256
Dazu muss einerseits die Klasse implementiert werden und andererseits die Klasse als Service registriert und mit dem Tag api_platform.subresource_data_provider versehen werden.
Dieser Tagging Mechanismus ist ein beliebtes Pattern bei der ApiPlatform, das du kennen solltest. Jeder DataProvider, der vom Framework beachtet werden soll, muss als Service registriert sein und mit dem entsprechenden Tag gekennzeichnet sein.
Das Framework lädt dann alle DataProvider und fragt diese nacheinander ab, ob sie für die angefragte Ressource eine Antwort liefern können. Sobald ein DataProvider eine Antwort liefert, wird die Schleife abgebrochen.

Mit dem neusten Stand des Branch api.2.3_subresource sollte es möglich sein folgende URL aufzurufen und die Dummy Adresse als Antwort zu erhalten (Caches löschen vorher): http://localhost/organisation/ABN-BBB/address

Todos
Ich habe einige Todos hinterlassen:

• Man müsste entscheiden ob die Adressen auch ohne eine Organisation angezeigt werden sollen, im Moment ist diese Route verfügbar: z.B. http://localhost/address/{id} Falls nicht müsste das irgendwie deaktiviert werden.

• Eine Resource muss gemäss API Platform eine ID haben. Gibt es sowas für die Adressen?
  

  hydra-swissbib.ch/src/Entity/Address.php

  Lines 55 to 60 in 162a256

  	/**
  	* @var string Identifier of a address resource
  	*
  	* @ApiProperty(identifier=true)
  	*/
  	private $id;

• Das Attribut für die Adresse heisst im Index hasAddress, im PHP Code aber address. Damit das Property Mapping funktionieren kann, sollten die Namen vereinheitlicht werden:
  

  hydra-swissbib.ch/src/Entity/Organisation.php

  Line 115 in 2861c10

  * Todo: define as vcard and rename to hasAddress that the property mapper can recognize this property

• Im Moment gibt der SubresourceDataProvider immer dieselbe Adresse zurück. Das sollte so angepasst werden, dass über den ElasticsearchAdapter die korrekte Adresse geladen wird:
  

  hydra-swissbib.ch/src/DataProvider/ElasticsearchSubresourceDataProvider.php

  Line 100 in 162a256

  //TODO retrieve correct address through Elasticsearch adapter and entityBuilder

• Die Adresse braucht eine IRI damit es keine Fehler gibt. Ich habe nicht gewusst was zu nehmen ist, deshalb habe ich einfach etwas hinzugefügt:
  

  hydra-swissbib.ch/src/Entity/Address.php

  Line 45 in 162a256

  * iri="http://i-do-not-know.com"

• Der SimpleEntityBuilder müsste so angepasst werden, dass er aus einer Elasticsearch Antwort auch verschachtelte Objekte wie die Adresse für eine Organisation erstellt:
  

  hydra-swissbib.ch/src/Entity/SimpleEntityBuilder.php

  Line 30 in 162a256

  * TODO implement subresource types like Address

[liowalter]

[hydra-swissbib.ch] subobject / adress

[guenterh]

Hallo Markus, (@maechler)

hier eine Zusammenfassung meiner Gedanken:

• Nachdem ich mir Deine Anmerkungen angesehen und in der Implementierung nachvollzogen habe, führten unter anderem zwei Sätze von Dir "...Ich musste das direkt aus dem Code herausfinden....", "...Eine Resource muss gemäss API Platform eine ID haben ...." dazu, dass ich mir gestern die lobid.og Implementierung der API für die GND - Daten heruntergeladen und analysiert habe.
  (https://github.com/hbz/lobid-resources/tree/master/web)
• Du kannst Dich vielleicht noch erinnern, diese API hatte ich als Alternative seinerzeit im Kopf, als wir über unseren Weg zur Implementierung von data.swissbib.ch diskutierten.
• Ohne hier in die Details zu gehen, drei Punkte, die mir an der API gefallen:
  a) Die Möglichkeit des einfachen Zugriffs realisieren sie (seit kurzem) über einen OpenRefine Endpunkt, der in der Bibliothekswelt grössere Vernreitung findet. Ich wollte dafür das Hydra Vokabular einsetzen. Allerings sind das verschiedene Ansätze und auch unterschiedliche Zielrichtungen
  b) Die Implementierung von Fabian ist in meinen Augen gut (fast so gut wie Deine...) und, da sie, ohne die Schwere eines "stark" prägenden Frameworks im Hintergrund mittragen zu müssen, einen kleinen Umfang hat, sehr übersichtlich und man kann sich rasch zurechtfinden
  c) sie baut auf dem in Scala/Java implementierten Framework Play auf. Nachdem ich einen Tag damit gearbeitet hatte, ging mir durch den Kopf: Meine Güte, warum tue ich mir das an, mich mit Symfony / API-Platform / immer noch ein wenig Zend zu beschäftigen, obwohl dort die Technologien die ich brauche, um endlich unsere data-processing umsetzen zu können, überhaupt nicht genutzt werden, ich mich völlig verzettele, am Ende zuwenig oder zumindet zu langsam liefere und auch bis zu einem gewissen Grad gefrustet bin, weil ich kaum Zeit finde, mich mit den für uns immer wichtiger werdenden Feldern zu beschäftigen.
• das aber nur als Zusammenfassung (ich werde schon wieder zu langatmig). Auch wenn ich den dringend benötigten OpenRefine Endpunkt mit lobid als Basis für uns schnell umsetzen könnte, gibt es auch dort noch Punkte, die überlegt sein wollen und bei der unsere bestehende Implementierung Vorteile bieten könnte.

Was ich dewwegen als nächstes machen möchte ist: zurück zu den Daten, diese nochmals anschauen und auf Basis der API Plattform prüfen, welche Modellierungsmöglichkeiten gegeben sind oder eben nicht. Ich möchte die Fragen beantworten:

• braucht jede Ressource eine API? Was machen wir zum Beispiel mit BlankNodes (die nur eine lokale _id haben). Was macht API-platform damit? Wenn wir hier eingeschränkt werden, ist das ein KO-Kriterium.
• In der RDF Datenmodellierung kennt man collections in verschiedenen Formen (geordnet / nicht geordnet). Was macht API-Platform damit? Im Moment brauchen wir diese noch nicht, das kann aber mal kommen.
• Generierung des Context durch API-Platform. Ich hadere damit bereits seit langem. Anders als in den sonstigen use-cases der API-Platform, bei denen in der Regel klassische Datenmodelle verwendet werden, ist dieser Context Teil unseres Datenmodells. In unseren bestehenden Usecases macht die Generierung durch API-Platform für mich a) keinen Sinn und b) schränkt sie uns stark ein, weil wir im Moment keine term-prefixes erstellen können. Darauf werden wir aber wohl sehr bald stossen, wenn wir anfangen, Konzepte miteinander verknüpfen zu wollen.
  Lobid hat bei der GND API hier, so wie ich das im Moment beurteile, weniger starke Anforderung, weil sie keine Splittung wie bei uns in Konzepte haben. Obwohl auch sie Daten des Entitityfacts service, Viaf, Wikidata .... verwenden und verknüpfen. Hierzu könnte ich noch einiges schreiben, das würde aber definitiv zu lange.
• kennst Du eigentlich unsere Implementierung "Einbezug unserer RDF Daten in www.swissbib.ch" ? Hier ein Beispiel:
  https://www.swissbib.ch/Record/023426233 wenn Du auf das i einer Person clickst, kommst Du auf die knowledge card dieser Person. Um die Daten zu erhalten, vernüpft die Implementierung mittels sequentieller Abfragen (und verwendet dazu übrigens den ESAdapter) mehere Konzepte. Mein Ziel ist es, dass die API diese Verknüpfung bereits macht, so dass auch andere clients diese Informationen nutzen können.
  An dieser Stelle kann die Konzept-Generierung der API-Platform Sinn machen. dafür möchte ich aber genau wissen, was machbar ist und was nicht.

Damit zum Abschluss:
Lass uns als nächstes die Varianten der Modellierung in der API-Plattform durchspielen (und ausprobieren). Ich möchte jetzt wiessen was geht und was nicht, bzw müsste man mit eigener Implementierung erweitern. Dies ist die Implementierungsseite.
Mit @sschuepbach, @Kordishal sowie @witzigs und @liowalter möchte ich mir nochmals die Modellierungsseite und die aktuellen und zukünftigen use-cases ansehen.

Ist das für Dich ein Weg und in Ordnung? Was geht Dir dazu durch den Kopf? Wenn Du das für richtig hälst, schicke ich Dir bald mehr Details.

[maechler]

Hallo @guenterh

Mein Gesamteindruck ist, dass wir relativ wenig Funktionalität der API-Platform wirklich nutzen. Das Framework ist vor allem stark wenn eine Datenbank verwendet wird, wenn Daten über ein UI bearbeitet werden sollen (Admin Component) und die Daten z.B. von einer Client-Applikation (React oder Vue.js) konsumiert werden.
In meinen Augen das Wichtigste, das wir vom Framework verwenden, ist die Anreicherung mit Hydra und die Dokumentation der Schnittstelle. Zusätzlich gibt es eine sinnvolle Struktur vor mit dem DataProvider und Encoder, das ist aber nichts, das man nicht auch nachbauen könnte. Mit ein Grund für die Entscheidung für dieses Framework war natürlich auch die Idee, dass Komponenten (sowie der ElasticsearchAdapter) für VuFind wieder verwendet werden können.
Wenn jetzt Hydra keine Anforderung mehr wäre oder man das Framework weiter aufbohren müsste um den Kontext direkt aus Elasticsearch zu übernehmen, dann stellt sich wirklich die Frage, ob das noch die richtige Technologie ist.

Ich finde den Weg, denn du vorschlägst sinnvoll. Ich gehe jetzt davon aus, dass ich mir die folgenden Fragen noch nicht ansehen soll sondern, dass ich noch auf weitere Details von dir warte.

• Braucht API-Platform die ID wirklich und wie gehen wir damit um?
• Sind geordnete / ungeordnete Collections möglich mit API-Platform?
• Wie könnte man den Context direkt aus Elasticsearch verwenden?

Ich kannte den Einbezug der RDF Daten in swissbib.ch noch nicht, das ist ein schönes Feature!

[guenterh]

Hallo @maechler

Danke für Dein Feedback.
Ich habe gerade nochmals in einem Dokument von Dir nachgesehen. In unserer Diskussion wurden seinerzeit 11 funktionale Hauptanforderungen (die meisten davon mit weiteren Unterteilungen) und 5 nicht-funktionale Anforderungen aufgestellt.
Beim Durchlesen bin ich erneut zum Schluss gekommen, dass Du und Melanie die Projektziele zu 100% und mehr erreicht habt.
Wie Du mit Deinem letzten Kommentar erwähnst, vor allem die Abstraktion der Backendservices (bei uns Elasticsearch). Potentiell hatten wir damals auch daran gedacht, mit dieser API ein Frontend für andere services wie Graphendatenbanken anzubieten. Ein solcher data-provider könnte gut in die von Euch entworfene Struktur eingebaut werden.

Mit diesem sehr generellen Ansatz sind wir, so mein Eindruck, aber auch an die Grenzen der aktuellen API-Platform gestossen. Diese versucht "allgemeinen" Datenstrukturen (im Falle der default-Implementation Daten im relationalen Modell) als response eines requests mit dem hydra-Vokabular anzureichern, um damit maschinelle, nicht auf eine bestimmte API fokussierte, clients zu ermöglichen. Wir haben das damals "Selbstdokumentation" der API genannt, so dass clients, bzw. die sie entwicklenden Menschen nicht erst die Dokumentation der Schnittstlle lesen müssen. Grundsätzlich stehe ich immer noch hinter dieser Idee (und wir werden auch von aderen dabei gestützt, z.B. https://ruben.verborgh.org/blog/2013/11/29/the-lie-of-the-api/ jemand der im Semantic web sehr aktiv ist)

Vor allem mir war damals auch sehr wichtig, dass wir es mit der Implementierung auch schaffen, Grundlagen für die Integration es ES servers in das VuFind Universum zu legen. (Steht so gar nicht mal in Deinem Anforderungsdokument). Aus diesem Gedanken ist dann der ESAdapter entstanden. Dieser wurde dann ja auch bei der Integration der linked-artefakte in https://www.swissbib.ch verwendet. Last but not least war dieses Kriterium dann auch ausschlaggebend dafür, dass wir uns für PHP als die Implementierungssprache entschieden haben.

So, ich denke, damit ist das Bild einigermassen abgerundet und auch für Dritte grundsätzlich nachvollziehbar.

Nicht nur aber auch nach dieser Diskussion ziehe ich folgende Schlüsse:

• im thread angesprochene Aspekte, die sich im Verlaufe der Zeit als wichtig herausgestellt haben, lassen sich nicht so ohne weiteres umsetzen bzw. ich müsste mich dahintersetzen, die durch API-platform vorgegebene Implementierung "umzubiegen" um dies zu ermöglichen. Ein Grund, für mich, liegt darin, dass wir unsere Infromationen bereits in einem Datenmodell vorliegen haben, in das die api-platform sie default umwandeln möchte
• mein Schwerpunkt bzw. ein Teil der Ziele des Projekts swissbib entfernen sich von PHP als Implementierungssprache. Um meinen "Zeithaushalt" noch in einem einigermassen vernünftigen Rahmen halten zu können, möchte ich mich von PHP langsam entfernen. Dies müsste man aus heutiger Sicht als "nicht-funktionale" Anforderung klassieren, die ich seinerzeit so noch nicht beurteilt habe.
• ich werde versuchen, Hydra als Vokabular zur Auszeichnung einer Response auch in der alternativen Implementierung zu verwenden. Dies allerdings in einem nachgelagerten Schritt. Zuerst möchte ich a) den in meinen Augen aktuell wichtigeren OpenRefine-Endpoint realisieren und dann b) möglichst einen GraphQL Endpoint. Zumindest a) sollte bis Ende 2018 abgeschlossen sein.

Vielen Dank Markus, dass wir das hier sehr offen diskutieren konnten. Ich möchte anderen vor allem im swissbib Universum damit die Möglichkeit geben, unsere Gedanken möglichst gut nachvollziehen zu können. Ich melde mich noch auf anderen Kanälen.