RE: Newbie questions about Issue tracker demo API

> -----Original Message-----
> From: Markus Lanthaler [mailto:markus.lanthaler@gmx.net]
> Sent: Thursday, May 01, 2014 10:36 PM
> To: public-hydra@w3.org
> Cc: McBennett, Pat
> Subject: RE: Newbie questions about Issue tracker demo API
> 
> Hi Path
> 
> On Wednesday, April 30, 2014 6:24 PM, McBennett, Pat wrote:
> > So I've just joined this Community Group (on behalf of D&B), and we've
> > very enthusiastic about contributing ideas and learning from the wider
> > group.
> 
> Great. Welcome on board!
> 
> 
> > As I'm so new I thought I'd try and 'catch up' in terms of
> > understanding Hydra. To prevent me asking dumb questions (at least
> > initially!),
> 
> By all means, please don't hesitate to ask (dumb) questions. We will all learn
> from them and they will certainly help us to improve documentation etc. as it
> will help us understand what newcomers are struggling with.
> 
> 
> > I thought I'd start by trying to understand a canonical example of a
> > Hydra Web API (even though 'canonical' will of course change as the
> > group progresses).
> >
> > So naturally enough I started with the Hydra Console and the Issue
> > Tracker demo (which was a great thing to model as an example by the
> > way!). But in fact I found it difficult to find the actual Hyrda JSON-
> > LD that describes this Issue Tracker Web API.
> 
> Yeah, it's a great example as almost every web developer is familiar with
> issue trackers. Unfortunately, however, Schema.org (being the most popular
> and well-known vocabulary), doesn't define the required concepts to model
> it. So I did the simplest thing and auto-generated a vocabulary for it.
> 

So just out of curiosity, I'm intrigued by what you mean by 'auto-generat[ing] a vocabulary'. Do you just mean because Schema.org doesn't define what an 'Issue' or a 'Comment' is, you added a 'vocab:Issue' and 'vocab:Comment' directly to your JSON-LD? If so, I would have said you 'manually created' an 'Issue Tracker' vocabulary for those things (and you just happened to lump that vocab into the Web API vocab for convenience). But maybe you really did auto-generate those terms in your JSON-LD using some sort of Java reflection code that looked at some Java (or PHP, or whatever) domain classes you've defined elsewhere to represent Issues and Comments (but I doubt it :) !)?

> 
> > Clicking around I came across the JSON-LD served up from 'http://www
> > .markus-lanthaler.com/hydra/api-demo/vocab#' (which I've included
> > pretty-printed below). But in talking directly to Markus (before
> > joining this group), apparently this JSON-LD is generated dynamically,
> > which leads into my first set of newbie questions:
> 
> Yep, that's true.
> 
> 
> > 1)  Is the whole point of Hydra that any Web API would publish at
> > least the description of its entrypoint as a single Hydra document
> > (whose serialization might default to JSON-LD, but presumably could be
> > in any RDF format, like Turtle, or N3, or whatever)?
> 
> Hydra describes how you can interact with resources exposed by a Web API.
> You can do that either inline or by putting all that information into a separate
> API description document. You are right, it could be any RDF format. Hydra
> was not designed to describe the domain concepts (things like Issue,
> Comment, etc. in the issue tracker example). That's the job of other
> vocabularies such as RDFS, OWL, and, to a certain degree, also Schema.org.
> 

Yep, I totally get this. We've done exactly that so far with our RDF and Hydra work, i.e. defined a base vocabulary for our basic terms (using simple RDF/RDFS/OWL (a little)/DC, etc., using Trig initially, but then Turtle to represent those), and then separate documents using Hydra (expressed currently in JSON-LD) to describe our Web APIs, which reuse (i.e. reference) the terms from the base vocabularies of course.

> 
> > a.  Just for manageability, I assume a large sophisticated API could
> > choose to publish individual parts of its API in separate Hydra
> > documents (each of which would be pointed to from a single entrypoint
> > API), but at least the entrypoint itself (i.e. the starting point)
> > should be encoded in a single Hydra document?
> 
> Certainly, you just have to make sure that a client can find it. Normally, you
> would reference the API documentation via an HTTP Link header [1]. The
> HydraConsole doesn't do that yet, but it's close to the top of my to do list to
> change that.
> 

Yep, I get that.

> 
> > 2)  If 1) is correct, then does the JSON-LD below really represent the
> > Hydra API for the Issue Tracker Web API?
> 
> It is a mixture of the vocabulary definition and the Hydra API documentation.
> The next example I'll create will probably use Schema.org as the vocabulary.
> Consequently, the API documentation will be much shorter and easier to
> understand.
> 
> 
> > a.  If it does, then I have a number of questions and suggestions, but
> > I won't mention them yet.
> 
> :-)
> 
> 
> > b.  If it isn't the definitive JSON-LD, then where is it.?
> 
> It is the "definitive JSON-LD", i.e., all the information the HydraConsole
> needs to work. Normally you would however want to clearly split that into a
> vocabulary definition and an API documentation.
> 

Yep, Ok, but this ties back to my first question above - how did you generate the current JSON-LD file? So far, we've been hand-writing our Hydra JSON-LD files, so I'm just curious to know if there is a 'better' way?

> 
> > 3)  Or have I missed the point completely, and Hydra Web APIs aren't
> > actually intended to be described in JSON-LD (or some other RDF
> > representation), but the API description (for example the Issue
> > Tracker JSON-LD below) is intended to be generated somehow from some
> > other form?
> 
> No, you got it completely right. It's my fault, mostly due to lack of time, that
> these things aren't clearer. Sorry about that. Any help to improve this and
> other things (tools, client libraries but also things like a nice homepage, a
> logo, etc.) would be greatly appreciated.
> 

I'm happy to try and rework the current 'Issue Tracker' JSON-LD to tidy it up somewhat (in my mind anyway), as that exercise should solidify a few of the minor quibbles and questions I have about it. Hopefully I can start that once I get the above issues clear in my mind (i.e. I don't want to start tweaking it by hand if there's some form of 'auto-generation' I should be thinking about instead!).

> 
> [1]
> http://www.hydra-cg.com/spec/latest/core/#discovering-a-hydra-powered-
> web-ap
> i
> 
> 
> --
> Markus Lanthaler
> @markuslanthaler

Received on Sunday, 4 May 2014 14:56:10 UTC