Re: some more feedback

Hey,

On Tue, Sep 16, 2014 at 8:12 PM, Markus Lanthaler
<markus.lanthaler@gmx.net> wrote:
>> [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?

I have no idea. I just didn't like having to infer that I could use
class to define a @type, I'd rather read "You can use a class to
express a few more things about a @type" or something like that.

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

Then shouldn't the spec express this? Maybe it does; I should read it
again. (what happens if two classes describe contradictory
information, i.e. one says a property is required and the other one
says it isn't.. Probably union again? What about writeonly and
readonly? I should check the spec for that too)

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

It would be rather odd marketing if premium partner operations were
not described as a Premium Partner (tm) feature in the main
documentation. :)

But the spec is not talking about two sets of documentation dependent
on what kind of user group you are in; the spec is  talking about
documentation that changes dynamically based on whether you happen to
have a permission or not. Don't you think the developer reading the
documentation needs to know that if a user gained permissions they'd
get more operation?

>  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 hope then that we can agree that the spec can do a lot better than
casually throw in a suggested solution to a use case that leads to a
lot of questions like mine while there are other solutions to this
same use case (like adding/removing types) that would handle this a
lot better in most cases.

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

Again, see my response above. This is not an argument in favor of the
text of the spec, I think.

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

I was not familiar with the Vary header, thanks! So the idea would be
for the documentation to return a Vary cookie header so that its value
won't be cached if the authentication token has changed.

I don't see how this resolves the problem:

* adding a permission to a user can change an existing user's
authorization; the token may still be the same.

* even if the token was changed each time authorization changes, there
is still no way to signal to the client that the API documentation
should be refreshed. *If* the client knew to reload API documentation
it'd get a new version, but how is the client supposed to know it can
do this? Any operation may potentially change a user's permission, and
there may also be external operations that cause the client's
permissions to have changed. Is the idea for the client to
continuously try to reload the API documentation before each request?

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

You think it's a feature to exclude a whole range of programming languages?

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

There's runtime and runtime. How does a Hydra service indicate to the
client that it should reload the documentation and regenerate its
types accordingly?

I wasn't aware that REST required that the types of resources
themselves can change on the fly. I thought it was about the client
having knowledge about the types of resources and how to follow links
between resources. Should I really assume nothing is stable and keep
trying to reload the API documentation before each request to the API
that it describes?

Good URLs don't break. If a URL describing the API suddenly, without
explanation, can add or withdraw operations and properties to classes,
isn't it negating on the implicit promise of backwards compatibility?

Thanks for getting back to my feedback; glad it was appreciated! I'll
explore a little more in the future I expect.

Regards,

Martijn

Received on Tuesday, 16 September 2014 20:03:35 UTC