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.


> 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.


> 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.


> 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.


> 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.


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


--
Markus Lanthaler
@markuslanthaler

Received on Thursday, 1 May 2014 21:36:40 UTC