RE: some more feedback

Hi Martijn,

On 4 Sep 2014 at 17:28, Martijn Faassen wrote:
> On Thu, Sep 4, 2014 at 4:00 PM, Markus Lanthaler 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.

Yeah, that sounds like a good idea. I noted it in ISSUE-24 [1]


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

Taking a step back on this. What else would you use with @type and how would you justify that?


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

Agreed.


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

A client can reasonably expect that it is supported. It won't find out for sure till it tries to invoke it (but that's a different story). From a Hydra perspective, attaching it to the resource itself, a property pointing to that resource or one of the types of that resource (or any combination thereof) is the same. The client simply takes the union of all operations and treats all of them equally.


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

Well, actually it is quite common that different user groups get (access to) different documentations. Think of premium partners etc. Anyway, that's just one way to realize such a use case. There are other options available as well (add/remove properties, add/remove types, embed operations in resource representation).


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

Again, it's just one way to implement such a feature and it might not be the best way to do it in all cases. One way to achieve what you describe above is to add a "Vary: Cookie" header in the response and change the cookie. "Vary: Authorization" and forcing the client to refresh its token would work as well.


> 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

I consider that a feature and not a bug :-)


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

Right. But really, you should do that all at runtime and not at design time. That's the whole purpose of using hypermedia (REST)


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

Sure. A link is nothing else than a property whose value happens to be another resource:

    "my-link": { "@id": "/link-target", "@type": "Deleteable" }



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

That's a good idea, thanks.


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

You mean download the representation of the entry point, right?


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

That's an interesting argument but I would say in that case you won't need much of the API documentation anyway.


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

OK. What if you look at it as specializing the content type? I mean, the content type is also specified in an HTTP header and not inline.


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

No, it doesn't say that. It says how you can discover the entry point. That doesn't mean that you have to follow that route. If you know the entry point already (and that's the normal case I'd say; look at the HydraConsole demos e.g.) then you discover the Hydra ApiDocumentation from there.


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

OK :-)


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

Fair enough. I raised ISSUE-69 [2] to track this.


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

Fair enough.

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

Yeah, good point.


>>> =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. :)

Great. Thanks a lot for the extensive feedback. This is extremely helpful and much appreciated!


Cheers (and sorry again for the delay),
Markus


[1] https://github.com/HydraCG/Specifications/issues/24
[2] https://github.com/HydraCG/Specifications/issues/69


--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 16 September 2014 18:13:21 UTC