Re: some more feedback

On Wed, Oct 1, 2014 at 7:13 PM, Markus Lanthaler
<markus.lanthaler@gmx.net> 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?

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

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

[snip]
>> You seemed to be saying that to be truly RESTful, the client also
>> needs to dynamically adjust its *interpretation* of the types (even
>> during a short-term interaction with the server), but I didn't think
>> that was a requirement. It may be a nice addition but you can still do
>> hypermedia without it.
>
> No, it doesn't need to adjust its interpretation.. but it might learn new things from the server that it can use. In this context that would be class/property relationships (super-/subclasses etc.). In the context of web browsers that's mostly JavaScript enhancements or now Web Components.

> Thanks for taking the time to write all of this down. Much appreciated

Thanks for your patience while I try to understand things!

Regards,

Martijn

Received on Thursday, 2 October 2014 14:05:43 UTC