some more feedback

Hi there,

I'm still confused about the Hydra spec, but I think such confusion
can only help improve the spec, so here's some more feedback. I've
learned enough to realize I can in some cases blame the draft spec for
my lack of understanding, instead of just my own ignorance and lack of
intelligence. So I've gotten a bit more critical here and there. The
criticism is very much intended to be constructive!

=the draft spec=

So Hydra lets you describe a RESTful web service. It builds on JSON-LD.

=Issue 3=

The figure in "Hydra at a glance" is not clear enough for me -- I have
no idea what's going on yet starting to read this spec, and this
doesn't really help make things more clear. I think such a figure, if
needed, should move somewhere below, perhaps into an appendix, so that
once concepts are more clear this might help fill in some gaps.

=Section 4=

It says an issue tracker will be used as an example. But while an
issue tracker is used in some example fragments, the document is not
driven by the perspective of an issue tracker at all.

I think doing so would be very enlightening to the reader. Talk about
how a client can find out the API documentation for an issue tracker.
Talk about how an issue has several operations. Talk about how an
issue can be queried using an IriTemplate. Instead of talking about
collections, you talk about how your issue tracker has a collection of
issues, and how we might interact with it, and so on.

You can start with a rough description in prose documentation of what
URLs the issue tracker has and what kind of content is on it, and then
show how we can turn this prose documentation into solid API
documentation and how we can also use some hydra vocabulary to
describe common types of content, such as collections.

=Section 4.1=

You talk about describing hyperlinks, and then you go into operations.
I'd suggest separating that into two sections. You introduce more than
enough new concepts in 4.1 just concerning describing links already.

Concerning those concepts, Example 3 is what? Example 4 is the
representation of a resource, but example 3 is part of the API
documentation, presumably. If it can be part of the representation of
a resource directly, please explain how, as I don't see it.

Example 3 and Example 3 relate to each other, I think, by way of the
@id "http:/api.example.com/vocab#comments". Example 3 says something
about that IRI, and example 4 then uses that IRI. This relationship
needs to be made extremely and abundantly clear. (if I even got this
right)

=Section 4.1: operations=

This should be in a separate section. You introduce a way to describe
operations. These operations, in example 6, are apparently part of the
representation of an issue, *not* part
of the API documentation. Or not; I'm not sure -- @id "/an-issue"
indicates to me this is a particular issue, but the description seems
to be describing the API. Which is it? This is extremely confusing!

When you talk about possible operations, don't only describe the
simplest possible form of interaction early on (the
DeleteResourceOperation), but also describe what a
CreateResourceOperaration looks like. I know you do that in 4.2
example 10, but 4.2 is not about operations. Just describing these
operations really could use a few more words in the spec.

The @context in example 6 bothers me a bit; I'd expect a context there
primarily pertaining to the representation of the issue, as opposed to
just the Hydra context. What would that look like?

==Section 4.2: documenting a web API==

I think here we might be going from a mostly part-of-resource inline
description as in 4.1 to a out of band API description. Is that
correct? I think you can do such a smooth switch because you describe
IRIs with JSON-LD and it doesn't matter where those IRIs are, in the
resource representation or the API documentation. Is that at all
correct?

Is example 8 supposed to be embedded in the supportClass structure
shown in example 7?

Example 7 has a section 'statusCodes' as a sibling to
'supportedClass'. But example 10 has statusCodes more sensibly as part
of an operation. I don't understand what the meaning is of statusCodes
in example 7. Ah, section 5.3 finally makes this clear. If you're
going to show statusCodes in the ApiDocumentation *and* Operation
classes both in section 4.2, then this should be described here, not
in 5.3

Why is it singular supportedClass, and plural statusCodes? You seem to
use singular in other cases, like for supportedProperty, what makes
statusCodes special that it should be plural?

This section talks about classes that are expected or returned by an
operation, but you didn't really demonstrate this in the operation
section before because you used the boring DeletResourceOperation.

Meanwhile, I'm also wondering what the relation is between Hydra class
and JSON-LD @type. You can use a class as a @type, which I see in the
Collections type, but that's not made clear here. And you can
presumably use the class in expects and returns in an operation. Or is
that really the @type? I think a class can be used to describe a type,
correct?

So in order to indicate what operations a resource supports I can
embed the supportedOperation and even supportedProperty directly in
that resource, but it's more succint and maintainable to associate
this information with classes. Is that correct?

Classes in addition allow you to go "closed world" for a type and say
things about the properties a class supports. Is this discussion about
closed world really necessary at this point? Can't you just say the
class allows you to express a few extra things about known properties
for that class?

Concerning example 8, I'd like to see an example concerning the issue
tracker, just like the other examples. This would help me in
particular when I see "property": "#property". What does this express
exactly? Why is the word "property" used and not something like "key"
or "name"? "property" seems strange to me - we're already in a
SupportedProperty type and now it has a key called "property"?

In general, when you have lists of things (supportedOperation,
supportedProperty, etc) have at least one example contain *two*
examples in that list, instead of only just one ever. This is easy if
you make the examples about the issue tracker.

Concerning example 10, I'm confused by the notion that operations can
also associate with a link:

* what if the supported operations for the link are inconsistent with
the operations for the class of what the link refers to?

* The notion to show only an operation if a user has a permission
implies there is not one API documentation but many, dynamically
generated based on current user permissions. That seems to totally
destroy caching, what am I missing? Alternatively all these operations
need to be embedded within the actual resource somehow and generated
dymamically, but I'm not even sure what that looks like in case of a
link (example please in that case!). And example 10 says
*documenting*.

For a GET operation I'd typically signal that in the resource
representation. If the user does not have a permission to GET a
resource, there's no property with a link in the resource, or there is
a property and it's null. Of course that assumes that there is no case
where a user may POST to a resource without being able to GET it...

Is this intended to work by having the documentation spell out
multiple types of links, i.e. a
"http://api.example.com/doc/#readonly-comments" and
"http://api.example.com/doc/#readwrite-comments" and then have the
content contain a reference to the link type somehow? If so, an
extensive example is needed that spells this out, as I don't even know
how the content could determine the link type.

Alternatively you could have some kind of special link node that
contains not only the IRI of what is being linked to, but also an
"allowedMethods" list which contains those methods that are allowed,
i.e. "allowedMethods": ['GET', "POST']. Is that possible?

= 4.3. Discovering a Hydra-powered Web API=

Now we finally discuss how a Hydra-powered web API is to be
discovered. This could help enlighten the reader to how things relate
to each other, but if so it should go earlier, and talk about how this
works for the issue tracker.

I see a way to use a link header to refer to the API documentation
from the home page. This implies my client is going to the HTML home
page first to pull out that link, and not directly to the API. What if
I go directly to the API, which seems to be the more common thing to
do? I.e. I already *know* the entry point?

Consider the case where there *two* different APIs on a site? The link
tag can return two references, and then I could look at the API
documentations somehow to determine the one I want to consume, and
then go to the entry point there. But it seems more reasonable to me
that I go to the right entry point of the API first, instead.

In discussions it was shown that the entry point (and all sub-points)
can also contain a link header to their documentation. This should
also be mentioned in this document.

But I'd still like to see this the other way around: you communicate
the entry point to the API to the client, and this contains a link
reference within the JSON (something like example 2) to the API
documentation. This seems to be the way links work within HTML
documents: a CSS document doesn't say what HTML document it's about,
but the other way around. Why should it be the other way around for
JSON and Hydra?

Having the entry point not part of the documentation also allows this
documentation to be used in multiple places -- if you have the entry
point baked into the documentation it only describes one host ever,
right (or at least prescribes the structure of the absolute path on
that host).

=5 Advanced Concepts=

I think the whole title of "advanced concepts" is a bit of a misnomer;
it's just a grab-bag list of things that aren't particularly more
advanced than anything else. In particular collections would be
happening all over the place. In fact, all of this stuff would be in a
typical API, even a read-only API. Instead if we had a worked out
example concerning an issue tracker we could build up to those
concepts step by step.

=5.1 Collections=

Here we seem to go back to talking about how Hydra can be used as a
vocabulary in resource representation itself, as opposed to being API
documentation. Is that correct? This needs to be made *very* clear --
if you think about Hydra as API documentation you stumble when you
suddenly see an example of a collection with concrete members with
concrete links, and vice versa.

=5.2 Templated links=

Are templated links supposed to be embedded in the resources or in the
API documentation? I think here we move back into the real of API
documentation again as an option. We already discussed my confusion on
how these are referenced. My understanding is that you can include
this directly within the resource description, or refer to it using a
IRI. Both ways of using these aren't immediately obvious, so it'd be
nice to see a more worked out example in the documentation. Really
seeing all the moving parts together, with an idea on what URL they
are, really is useful. I realize JSON-LD allows a variety of
organization of nodes, but a few basic examples would still help the
reader a lot. Instead example 15 leaves the reader to wonder where
this whole IRI template is supposed to be.

Example 16 is not really an example. It's a definition. Instead I'd
like to see a real example where the search property is used.

=5.3 Description of HTTP Status Codes and Errors=

Typo: "The address this issue," -. "To address this issue,"

See section 4.2 for a discussion of how I think some of this should be
moved to earlier in the text.

=The API Demo=

I tried to figure out how an issue tracker is described by going to
the Hydra API demo using the Hydra console:

http://www.markus-lanthaler.com/hydra/api-demo/

But unfortunately using the browser console was rather more confusing
than it should be. Firstly, can the demo server send back
pretty-printed JSON? It's a demo server, after all.

The stuff on /api-demo includes all sorts of __activectx and __value
information; it'd be better if that kind of normalization was done on
the client-side so that the reader is not exposed to it.

Understanding the large graph at
http://www.markus-lanthaler.com/hydra/console/proxy.php?url=http%3A%2F%2Fwww.markus-lanthaler.com%2Fhydra%2Fapi-demo%2Fvocab&vocab=1
(confusing URL!) is also not easy.

Regards,

Martijn

Received on Tuesday, 2 September 2014 13:15:57 UTC