RE: some more feedback

On 6 Okt 2014 at 14:16, Martijn Faassen wrote:
> On Mon, Oct 6, 2014 at 1:42 PM, Markus Lanthaler 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.

This is an excellent argument. Maybe all we need to do is to describe it slightly differently and include a couple of examples. So we describe how it can be used to realize certain use cases but do not describe the relationship to RDFS etc. (it is in the machine-readable definition of the vocabulary for people that care though). In other words we don't describe *why* it is used with JSON-LD's "@type" or Turtle's "a" but just describe how you do it and what features/use cases this enables.

How does that sound?


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

Right, the API provider could publish that documentation publicly. It would, however, likely be a different ApiDocumentation than a one that is then referenced from resources in the API itself.


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

No, you would have two or more ApiDocumentations. For instance

   http://developers.example.com/api-doc.jsonld

which includes *all* operations regardless of the permissions. The natural-language descriptions would make it clear that some operations may not be available to all users as they depend on their permissions. A resource could then nevertheless reference another ApiDocumentation at runtime:

    GET /users/ HTTP/1.1
    Host: api.example.com
    
    ====================================
    
    HTTP/1.1 200 OK
    ...
    Content-Type: application/ld+json
    Link: </api-doc/dynamic.jsonld>; rel="http://www.w3.org/ns/hydra/core#apiDocumentation"

You could use exactly the same tool to generate the nicely formatted HTML documentation but obviously the result would be different. What do you think?


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 6 October 2014 12:40:43 UTC