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