RE: some more feedback

I didn't forget about this, Martijn. I just haven't found the time to respond. I'll get back to you (and others) by the end of the week.



On 4 Sep 2014 at 17:28, Martijn Faassen wrote:
> 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 Tuesday, 9 September 2014 18:04:48 UTC