Re: some more feedback

Hi there,

On Mon, Oct 6, 2014 at 1:42 PM, Markus Lanthaler
<markus.lanthaler@gmx.net> wrote:

> The Hydra Core Vocabulary defines the hydra:Class concept, you are right. But if you look at its definition you'll see that it is a subclass of rdfs:Class with
> the tweak additional information that instances of hydra:Class are dereferenceable Web resources instead of being "just" identifiers. In RDF, all IRIs are
> identifiers but not all are necessarily locators, i.e., URLs. Hydra makes this distinction explicit. Back to  your question, the thing you use with @type is
> rdfs:Class (and its subclasses). That's why I said that I don't think the Hydra spec is the place to describe this. But if it really confuses you (and others) we
> can certainly add a statement to the spec.

But this points out something that I hadn't fully realized until just
now, though I had my suspicions.

This implies the Hydra specification is not really for people like
myself, who are unfamiliar with RDF. You really need to understand RDF
in order to apply Hydra.

I find that pretty unfortunate. It's okay with me that Hydra is
informed by RDF, is compatible with RDF tools, can be interpreted as
an RDF specification. That's what JSON-LD does. But to me, if I have
to *understand* RDF in order to understand Hydra, I find Hydra much
less attractive.

>> It'd be dependent on the permission of the developer learning about
>> the system. The user is not the one interested in the API
>> documentation, they just use the client software that uses the API
>> documentation. The developer is, and you may not want to show them
>> certain operations exist, but that would be dependent on what
>> permissions the developer has.
>
> So your assumption is that a developer would be reading the API Documentation serialized in the form of, let's say, JSON-LD or Turtle directly instead of
> reading a nicely formatted HTML version thereof which could be a superset including all potential operations etc.?

No, I was expecting nicely formatted HTML for the developer. But these
developers do not have to be logged in with a particular user's
permission in order to see the documentation.

Is the idea that the API documentation HTML is generated by special
client software that does log in with the right user permissions? If
so, this explicitly seems to exclude the use case where the developer
uses a client-side tool only to generate readable HTML documentation,
right? If you want to decouple user permissions from developer
permissions, some server intermediary would be required that can log
in with the correct user permissions.

Regards,

Martijn

Received on Monday, 6 October 2014 12:17:20 UTC