Hydra W3C Community Group Telecon

Minutes for 2019-11-26

  1. Ontology discover and multiple API documentations
Action Items
  1. Add an informational paragraph to the specs with hints on how to treat additional data from the API documentation
Karol Szczepański
Tomasz Pluskiewicz
Sebastien Lambla, Tomasz Pluskiewicz, Karol Szczepański
Audio Log
Karol Szczepański: Meeting: Hydra W3C Community Group Conference Call
Tomasz Pluskiewicz is scribing.

Topic: Ontology discover and multiple API documentations

Karol Szczepański: ok, I understand we have a hypothertical SPA which consumes multiple APIs
Sebastien Lambla: let me explain our scenario...
... we have a data marketplace, with multiple dataset, where you can purchase
... each has various types of data
... quite large, ontologies, 100s of types. all in the same API
... we have multiple providers behind the scenes
... a client would purchase data and get different vairables, specific to that dataset
... we will provide a list of context document defining the terms
... but the context does not provide all metadata at type level
... right now we have an API Documentation, which could be a good point to load the metadata
... so that we can discover schemas
... we settled on keeping one API Documentation
... the difficulty is that spec does not say you can retrieve type informaition on per-request basis
... the spec suggests there is one api documentation
... and there will be the same
... another issue is that there is what happens when there are multiple api documentation links
... last issue, if I describe a class in api doc, it becomes a resource the can be identified
... so if I use reasoning everything can potentially be dereferenced
... so maybe hydra:supportedOperation should have range extended to hydra:Resource
Karol Szczepański: if an API supports certain class, it means that it can manipulate instance thereof
... loosening it may be tricky
Sebastien Lambla: for example I have a resource which supports a type which is rdfs:Class
... I want to be able to discover information about the rdfs:Class
Karol Szczepański: sounds like all you need is just to dereference that class to understand what it is
Sebastien Lambla: but I cannot dereference like, 500 classes
Karol Szczepański: so those are no hash URIs?
Sebastien Lambla: yes some are, but it's still many ontologies
Karol Szczepański: another idea is to provide these ontologies within the API Documentation. it's still a graph
Sebastien Lambla: that would change JSON-LD harder to consume
Karol Szczepański: yes, you might get an array of nodes
Sebastien Lambla: yes, but a generic client will not implement it the sme way
... so I'm saying that maybe api doc could have something extra, which is plain RDFS
Sebastien Lambla: I need a second way of discovery
... feels like something is missing
Karol Szczepański: I don't have an answer
... supported classes and properties is something different than plain data models
Sebastien Lambla: with Open API you can combine all those information
... and with hydra I would want one document with all the operations and all data models
... if it's not in a generic client, I will struggle making hydra compelling
Tomasz Pluskiewicz: you could use prefetch links [scribe assist by Karol Szczepański]
... so the ontologies can be hinted so the client can preload them earlier
Sebastien Lambla: I could have mutliple top level nodes in the API doc
... but from a generic client, I'm concerned about anything we do but is not in the spec
... if the in the API doc graph we would allow disconnected graph
Tomasz Pluskiewicz: I would love to see a full-blown example
Sebastien Lambla: we will have a draft in a few weeks once we launch
Tomasz Pluskiewicz: I had similar example with multiple API documentations - a books API that links books to reviews, but reviews is handled by another API [scribe assist by Karol Szczepański]
Tomasz Pluskiewicz: solution would be to have always to give two API documentations or just to keep API documentation that you've received and combine it somehow [scribe assist by Karol Szczepański]
ACTION: Add an informational paragraph to the specs with hints on how to treat additional data from the API documentation