RE: some more feedback

On 2 Okt 2014 at 16:05, Martijn Faassen wrote:
> On Wed, Oct 1, 2014 at 7:13 PM, Markus Lanthaler wrote:
>> On 24 Sep 2014 at 12:06, Martijn Faassen wrote:
>>> On Wed, Sep 17, 2014 at 6:28 PM, Markus Lanthaler wrote:
>>>> On 16 Sep 2014 at 22:03, Martijn Faassen wrote:
>>>> [snip] Unfortunately, I don't understand what you mean by
>>>> 
>>>>> I'd rather read "You can use a class to
>>>>> express a few more things about a @type" or something like that.
>>> 
>>> As far as I understand, the Hydra spec doesn't actually make explicit
>>> that I can use 'class' to define something I can use in @type. I have
>>> to infer this from the context of how they're used in various
>>> examples. I'd just prefer it if it actually said so out loud.
>> 
>> Well, the Hydra spec isn't really the right place to do this but we can
>> certainly add a sentence or two if it confuses other people as well.
> 
> This confuses me a lot. Doesn't the Hydra spec introduce the class
> concept? Why not make explicit that it can be used to describe things
> that you then refer to using @type?

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.


>>> Sure, it depends, but I think I'm describing a common assumption here:
>>> that we typically expect the documentation to be static, and not
>>> depend on permissions. I can see how you might want to generate
>>> different documentation profiles that are permission-based and that in
>>> some documentation profiles the operation is missing, but such a
>>> profile would not be dependent on the permission of the user of the
>>> service under description.
>> 
>> ... but on?
> 
> 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.?


>> Unless the cache metadata explicitly tells you it's out of date, I
>> wouldn't proactively try to refresh it as it may change exactly in the
>> moment you invoke the operation. Wait till something fails (in most
>> cases that will never happen) and try to
> recover.
> 
> Yeah, that's one notion I had too. I think the spec could have some
> text about it:
> 
> If an operation specified by the API documention as valid fails, this
> may be due to out of date API documentation. In such a case, the
> client should reload the API documentation.
> 
> This seems to be the best way to deal with out-of-date specs.

Good idea. I tweaked your text above a bit and added it to the spec:

  https://github.com/HydraCG/Specifications/commit/643a8e19bad1aa4da05e37f16b94e98b21192fdd


Thanks,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 6 October 2014 11:42:42 UTC