Re: some more feedback

Hey,

On Thu, Sep 4, 2014 at 4:00 PM, Markus Lanthaler
<markus.lanthaler@gmx.net> wrote:

[the figure]
> OK. What this figure is trying to do, is to give you an overview of the
> vocabulary that Hydra defines... but of course that doesn't help you if you
> are not used to using vocabularies in the first place.

I think it would make more sense and be less intimidating if the
figure was in an appendix. You can say "if you're already familiar
with RDF and vocabularies, please check the appendix for a picture
giving an overview", or something.

[relationship between Hydra class and JSON-LD @type]

Where does the text of the specification actually say that you can use
a class in a @type? You have to infer it from examples, I think.

>> 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?
>
> No, "supportedOperation" has to be associated to a class. You need to use
> "operation" if you want to associate an operation to an instance (resource).
> supportedProperty doesn't make that much sense for instances AFAICS

Ah, right, I hadn't noticed the difference between 'operation' and
'supportedOperation'. I think that's why it is important to make
explicit which part of Hydra can be part of the resource
representation and which can only be in the API documentation.

>> 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?
>
> What do you mean by "inconsistent" in this context? They don't have to be
> the same if that's what you are saying. The resource that is the target of
> the link will be known to support both the operations associated to the link
> property and the operations associated to its class(es).

Well, what if a class doesn't define a deleteOperation is supported
but a link to a resource of that class says you can? Is it or isn't
it?

>> * 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?
>
> Shared caches perhaps, not private caches (as the one in your browser e.g.)
> though.

It's rather surprising to see the notion of dynamically generated API
documentation dependent on user permissions to be so casually
discussed. People don't generally expect that API documentation can
change on the fly as you interact with the system. Isn't one of the
points of having documentation that you can read it and get an idea of
the capabilities of the system, including capabilities you may not be
having a permission for? I realize that having api documentation can
also be used to automatically generate interfaces and user interfaces,
but you do call it *documentation*, not a "capability description
based on current user permissions".

I don't see how the browser cache can be useful by the way -- what if
client fetches the API documentation, *then* in the course of
interaction gains a permission that affects the API documentation? How
does the client know it should refetch the API documentation? Without
a notion of "okay, that operation you just did? please refresh the API
documentation you already have", it would have no idea.

It also makes the idea of generating a programming language API for a
web API statically rather more difficult, as there is not a single API
documentation anymore. Dynamically generation of such an API is still
possible, but still needs "okay, the previous API documentation you
got is now invalid, please change the methods of the JavaScript
objects that proxy resources accordingly" which is rather complicated!

> That's one option. The simpler one in many cases is to introduce a new class
> (CommentCollection, WritableCommentCollection) and add/remove it as
> necessary in the resource representations.

I can see how that works where I have classes, but weren't we talking
about links and supported operations for them? Can you use a class for
links?

>> = 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.
>
> The thing is that this is not strictly necessary if all the operations are
> declared inline (embedded into resource representations). In that case, you
> won't need a Hydra ApiDocumentation unless you want it to point to the
> EntryPoint.

I talked earlier about making the difference between embedded
information in representation and API documentation abundantly clear.
You can still talk about the issue tracker, first going as far as you
can embedding information, and then describing how you can lift some
of that embedded information into classes and such, into an api
documentation, and what benefits doing so would bring.

[snip]
>> 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
>
> Why is that preferable over an HTTP Link header?

* You can download the document as a file and get all the information you need

* It makes it possible to publish a bunch of files over HTTP as a
read-only API without any particular server support to add a header.

* It's similar to what you can do with a @context URL in JSON-LD.

That isn't to say a header isn't a useful option sometimes, it just
ran counter to my expectations.

>> 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?
>
> Because we also want to support the use case which requires to find the
> entry point. Basically every (human-readable) API documentation contains
> this. Hydra is no different in this regard.

Links on the current web tend to go to a resource, not to a
description of a resource and then to the resource. That's how we
explore the web. Additional information about resources that help you
interpret it or represent it such as CSS come second, referenced from
that resource.

In the current spec say: no, Hydra comes first, you fetch the Hydra
docs first and *then* it tells you where the actual thing you want is.
I can see how this is a use case, and I can see the parallel with
human readable documentation, and I can see how you could generate
human readable documentation from this (though the notion of dynamic
generation of Hydra content dependent on permissions defeats that
too!). But it runs rather counter my expectations.

I'd like to see the use case described where the entry point comes
first, it points to the Hydra docs, and the Hydra docs doesn't have to
specify an entry point. And then secondarily describe the use case you
have now where the entry point is embedded in the Hydra content.

> Well, in that case you either don't specify an entry point at all or
> enumerate all of them (if you know them). Nothing will break by doing so but
> obviously you won't find the entry point if it isn't specified.

The spec doesn't really say you can do that; it totally goes with the
use case that you really want the Hydra docs first.

So imagine I am interested in a particular web API that a site offers.
Imagine that site offers multiple APIs (or multiple incompatible
versions of an API). The current doc suggests to me that I should:

* go to the home page of the site (that returns HTML, most likely)

* fish out the Link header. There are two links in there, to two
different Hydra API documents.

* I somehow know which one I need. (How could I do that without
reading actual documentation? why would that documentation not contain
the actual entry point I need?).

* I follow the link to that, and then find the entry point.

I consider that a rather implausible scenario. It's much more likely I
already know which entry point I want.

I understand how getting the docs first through a link header is *a*
use case, where you want to build a tool that can explore arbitrary
web sites and dig out API documentation automatically, so I can see
how you want to support it. I can see how doing that opens up all
kinds of possibilities! But it's not the predominant use case for web
services today, and I think the spec should recognize that. Right now
it just suggests I go with an entry point in the docs.

>> =5 Advanced Concepts=

[me questioning the notion of advanced]

> Do you feel the same about IriTemplates for example?

Yes, because many, probably most, REST APIs are going to want to use
URL parameters in one place or another. So the main documentation
needs to at least tackle the basic use cases there. You could leave
templates for other parts of the IRI to a later, more advanced
section.

I'd prefer a spec that built up a story, introducing concepts step by
step, covering concepts that you're likely to need earlier than
concepts that you're less likely to need. URL parameters you are
likely to need, but parameterizing the path is may be less common.

I'll keep exploring and you'll likely hear from me again at some point. :)

Regards,

Martijn

Received on Thursday, 4 September 2014 15:28:52 UTC