RE: Newbie questions about Issue tracker demo API

On Sunday, May 04, 2014 4:56 PM, McBennett, Pat wrote:
> On Thursday, May 01, 2014 10:36 PM, Markus Lanthaler wrote:
> > On Wednesday, April 30, 2014 6:24 PM, McBennett, Pat wrote:
> > > 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 :) !)?

It's the latter. The issue tracker demo API is written in PHP. The entity
classes are here:

 
https://github.com/lanthaler/sfHydraDemoApp/tree/master/src/ML/DemoBundle/En
tity

You'll see that those classes are annotated. For example the $title property
of the Issue class is marked as annotated with which tells the HydraBundle
to expose this field when serializing such an entity to JSON-LD. Since
there's no vocabulary IRI associated to that field, the bundle generates one
automatically. That is, it mints a URL of the form vocab:Issue/title and
documents it by using the DocBlock's information (title, description, range,
___domain). This then forms the ___domain vocabulary (similar to Schema.org) that
is being used in the Hydra API documentation.

If there would already exist such a vocabulary (there might, I haven't
really checked), you could simply say that this specific property should be
exposed as, e.g., schema.org/name. That way you could get rid of that
automatically generated vocabulary and just expose the Hydra API
documentation instead.


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

Great. Is some of your work publically available?


[...]

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

The HydraBundle [1] does that by leveraging annotations on the entities [2]
and controllers [3]. In fact, if you just have a simple CRUD application,
the controllers' code can be generated automatically. I gave a talk at
Symfony Live last year. You might wanna watch it on Youtube [4].


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

If you want to help on this, it might be more interesting to create a new
API. A while ago I was discussing with Ruben the creation of an exemplary
events API. That ___domain is quite well represented in Schema.org and allows a
number of interesting interactions/queries. The API could nevertheless be
quite simple.. there would be events (perhaps Festivals,
http://schema.org/Festival), locations, and performers. If we want, we can
then extend it to also represent tickets and thus model a simple eCommerce
showcase API. Would that interest you? Who else would like to help to make
this happen?


[1] https://github.com/lanthaler/HydraBundle
[2]
https://github.com/lanthaler/sfHydraDemoApp/tree/master/src/ML/DemoBundle/En
tity
[3]
https://github.com/lanthaler/sfHydraDemoApp/tree/master/src/ML/DemoBundle/Co
ntroller
[4] http://bit.ly/sl-portland2013-video


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 12 May 2014 14:08:18 UTC