Hydra W3C Community Group Telecon Minutes for 2017-12-11

Thanks Pavlik for scribing. The minutes from this week's telecon are
now available at

   http://www.hydra-cg.com/minutes/2017-12-11/

The full text of the discussion is below, including a link to the audio
transcript.


-------------------------------------------------------------------
Hydra W3C Community Group Telecon Minutes for 2017-12-11

Agenda:
  https://www.w3.org/community/hydra/wiki/Conference_Calls#2017-12-11
Topics:
  1. Holiday break - when should we have our next call?
  2. Follow-up on action items
  3. Update from Bergi about his work
Resolutions:
  1. Pause telecons over the holidays, next telecon will be on 
    January 8th
Action Items:
  1. Karol to create a pull request documenting stuff like 
    hydra:memberTemplate in the spec as the reference client already 
    uses them
Chair:
  Markus Lanthaler
Scribe:
  elf Pavlik
Present:
  Tomasz Pluskiewicz, elf Pavlik, Thomas Bergwinkl, Markus 
  Lanthaler, Karol Szczepański
Audio:
  http://www.hydra-cg.org/minutes/2017-12-11/audio.mp3


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
Thomas Bergwinkl: 
  https://github.com/zazuko/wikidata.zazuko.com/blob/master/api/api.json#L39
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: 
 
https://github.com/zazuko/wikidata.zazuko.com/blob/master/api/spaceprobes.sp
arql
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!

Received on Monday, 11 December 2017 20:12:27 UTC