Hydra W3C Community Group Telecon
Minutes for 2017-12-11
- Agenda
- https://www.w3.org/community/hydra/wiki/Conference_Calls#2017-12-11
- Topics
- Resolutions
- Action Items
- Chair
- Markus Lanthaler
- Scribe
- elf Pavlik
- Present
- Tomasz Pluskiewicz, elf Pavlik, Thomas Bergwinkl, Markus Lanthaler, Karol Szczepański
- Audio Log
elf Pavlik is scribing.
Topic: Holiday break - when should we have our next call?
Markus Lanthaler: next one on Dec 25th, after that we have Jan 8th
elf Pavlik: for me anything from Jan 8th works
Tomasz Pluskiewicz: +1
Karol Szczepański: +1
Thomas Bergwinkl: +1
PROPOSAL: Pause telecons over the holidays, next telecon will be on January 8th
Markus Lanthaler: +1
elf Pavlik: +1
Karol Szczepański: +1
Tomasz Pluskiewicz: +1
Thomas Bergwinkl: +1
RESOLUTION: Pause telecons over the holidays, next telecon will be on January 8th
Topic: Follow-up on action items
Markus Lanthaler: 1. Markus to render the use case documents on the Hydra homepage (hydra-cg.com/11)
Markus Lanthaler: http://www.hydra-cg.com/drafts/use-cases/2.api-documentation.md
Markus Lanthaler: I replied to agenda email with an example of rendered use case ^
... I appreciate feedback
... we miss links between those files and Table of Contents
... this ties to next action item
Tomasz Pluskiewicz: I agree, we should push something visible (linked)
... event if we don't have the documentation perfect yet
Markus Lanthaler: 2nd action was on Tomasz to come up with a rough structure of how the documentation should look like (hydra-cg.com/12)
s/event/even/
Tomasz Pluskiewicz: probably best to look at some other good examples
... for example Swagger documentation
Tomasz Pluskiewicz: https://swagger.io/docs/specification/describing-parameters/
... I would start with ToC on the left
... I currently implement templates so we could get an article about templates
Karol Szczepański: I find Swagger documentation overwhelming
... but more or less I agree about the direction, possible restructuring it a bit
Tomasz Pluskiewicz: we wouldn't start with documentation that overwhelming, swagger has grown that documentation over long time
Karol Szczepański: agreed
Karol Szczepański: How updating the markdown on github will reflect on the page?
Markus Lanthaler: it will update automatically
Markus Lanthaler: process wise will you create PR for that?
Tomasz Pluskiewicz: yes, I'll start with something in use-cases directory
Markus Lanthaler: anything else on those two action items ?
Thomas Bergwinkl: we currently work on HTML interfaces to API description
... and want to have example data
... we want to describe it in triples and have access to them
Markus Lanthaler: i see it as combination of what you said
... most of the information stays in github issues, mailing list conversations and sometimes even our heads
... we should improve it by having more discipline with adding documentation which includes examples
... in parallel we have amazing work by Karol_Szczepanski with reference client implementation (Herakles.ts)
... we should also be able to write snippets showing how one can interact with API using that reference client
Markus Lanthaler: mostly we want to document the decisions we make and drive with it implementation of reference client
Thomas Bergwinkl: do you want to convert that documentation to RDF data ?
Markus Lanthaler: could you clarify what do you mean by that
Markus Lanthaler: tpluskiewicz referenced swagger just as an example
Thomas Bergwinkl: http://www.hydra-cg.com/drafts/use-cases/2.api-documentation.md
Thomas Bergwinkl: will that information from those example snippets get converted to RDF triples?
... example about request and matching response
Thomas Bergwinkl: maybe we will do something and we could convert it for Hydra doc, please get in touch with me
Markus Lanthaler: do you have something we could take a look at?
Thomas Bergwinkl: I could show some stuff we currently work on
Markus Lanthaler: we already finished with our agenda, I see no problem to go into that
Tomasz Pluskiewicz: one more note about rendering, I would prefer to have the .md removed from URLs
Markus Lanthaler: why would you like to have it gone?
Tomasz Pluskiewicz: looks like leaking implementation details
Markus Lanthaler: this way I can do very easily Apache rewrite
Tomasz Pluskiewicz: not a big deal for me
Karol Szczepański: the latest Herakles.ts PR stays outside of Hydra spec boundries
it uses 'hypothetical' `hydra:memberTemplate`
Markus Lanthaler: would you like it added to the vocab or spec?
Karol Szczepański: I leave it up to you, I would prefer to have client that complies to spec and uses official vocab
Markus Lanthaler: we could at least update the vocab, I wouldn't worry about the spec to much and accept it getting little 'outdated'
Karol Szczepański: I'll make PR
Karol Szczepański: good enough for me to just update the vocab
ACTION: Karol to create a pull request documenting stuff like hydra:memberTemplate in the spec as the reference client already uses them
Markus Lanthaler: anything else to discuss before we talk about bergi's work ?
Markus Lanthaler: let's give bergi's the floor
Thomas Bergwinkl: https://github.com/zazuko/hydra-view
Topic: Update from Bergi about his work
Thomas Bergwinkl: we use it for pagination, will rename to hydra-box
Thomas Bergwinkl: https://github.com/zazuko/wikidata.zazuko.com/tree/master/api
... besides hydra description itself we also point to the code
Thomas Bergwinkl: http://wikidata.zazuko.com/api
... you can see HTML rendering of triples, we really want to have nice interfaces
Thomas Bergwinkl: https://github.com/zazuko/wikidata.zazuko.com/blob/master/api/api.json
... we also accept SPARQL query and we use ES6 string templates for them
Markus Lanthaler: can you explain the overall concept of what you build?
Thomas Bergwinkl: open data, statistics data - something that many people will want to consume the data
... we want to make it generic and reusable
Thomas Bergwinkl: http://wikidata.zazuko.com/api/spaceprobes/?from=2010
Thomas Bergwinkl: we upgraded my hydra client
Thomas Bergwinkl: https://github.com/zazuko/hydra-fetch/tree/develop
... the live example doesn't fully follow Hydra spec, but the github code already fully follows it
here we map variables from triples to variables
... we also define return frame for JSON-LD
... we don't want to force developers to think about Linked Data
Thomas Bergwinkl: we also have something similar for CSV on The Web
... we would like to get together with other people interested
Markus Lanthaler: i miss the link between what we talked about our documentation (Hydra CG)
... you mentioned 'executable documentation'
Thomas Bergwinkl: if you would define triples we would use them
... we really want to have interactive documentation
Markus Lanthaler: very cool work!
Markus Lanthaler: do you see anything missing in Hydra or causing problems?
... implementations of templates we found little difficult
... also the variables mapping
... where we use ES6 templates
... we thought about have IRI templates for variables
... to create NamedNodes
... we still don't see best way for resolving templates
Markus Lanthaler: IriTemplates we discussed during last telecon and may tackle it next
... currently still underspecified
Thomas Bergwinkl: I will join more telecons in a future and again participate more
... I can show little more of the prototype once we document it better
Markus Lanthaler: thank you for sharing your work!
Thomas Bergwinkl: i plan to use Hydra not only on HTTP
... to have microservices and use hydra operations even for human tasks in workflows
... input and output of examples could maybe event get described with tripples
s/tripples/triples/
Thomas Bergwinkl: we have 'protofetch' where you can register different handlers for different protocols
Markus Lanthaler: we had conversations about abstracting the protocol away, but want to figure out HTTP first
elf Pavlik: not relying on HTTP verbs sounds like a good approach here
Markus Lanthaler: anyone wants to comment or discuss something else?
Tomasz Pluskiewicz: how does the link of your variables relates to IriTemplates
Thomas Bergwinkl: in the same folder you can find SPARQL template, where we use again those variables
... we convert subject to a blank notes, use all properties as predicates and use values as subject
s/as subject/as objects/
Thomas Bergwinkl: maybe we should make it a part of the code itself
Markus Lanthaler: bergi have you looked at Herakles.ts
Thomas Bergwinkl: myself not a big fan of TypeScript, we also have very simple client
... we also want to have 'in memory' protocol and it seems difficult to add to Herakles.ts
... we continue with hydra-fetch client
Markus Lanthaler: I mostly wondered if you have some feedback on Herakles.ts based on your hydra-fetch implementation
Karol Szczepański: any specific plans for upcoming bigger break
... I would grab next use case, maybe the 'search'
Markus Lanthaler: great if we can make progress on Herakles
elf Pavlik: I may look at replacing `hydra:search` property with `schema:SearchAction` type
Markus Lanthaler: Noted Pavlik. Thanks!