RE: some more feedback

On 16 Sep 2014 at 22:03, Martijn Faassen wrote:
> On Tue, Sep 16, 2014 at 8:12 PM, Markus Lanthaler 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,

Well, @type is a property. It relates a node or a value (@value) to a type. A type is represented by a class (in case of nodes) or a datatype (in case of values, a more specific class of classes, i.e., rdfs:Datatype rdfs:subClassOf rdfs:Class).

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.




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

Yes, it should. We definitely need to make this clearer - this already cause confusion in the past. I raised ISSUE-71 [1] for this.


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

They are different classes, how could it be contradictory?


> Probably union again? What about writeonly and
> readonly? I should check the spec for that too)

That's indeed a problem. We thus decided in ISSUE-14 [2] to rename readonly/writeonly to readable/writeable


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

I don't think I can give you a general answer to this question. It depends. As said before, this is not always the right thing to do and there are alternative to achieve the same.


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

Yes, I agree 100%.


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

It's one possible solution. You can also prepare a set of static documentations based on permissions and modify the HTTP Link header accordingly.


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

Obviously you would have to change the token, i.e., overwrite the cookie or force a token refresh.


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

By the Vary header. It says: if you cache this, take care that it depends on these headers (Cookie, Authorization, ...), not just the URL. As soon as they change, the cache is automatically invalidated.


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

Nope, see above.


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

No, and we don't exclude a single programming language. We just make certain (brittle) designs more difficult.


>>> 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 hope my reply above answers this question, if not, let me know.


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

I don't know what you mean by "the types of resources". You get a response from the server and should be prepared that it might look different than what you expected. Of course it is in the interest of the API provider to minimize surprises and not introduce breaking changes. 


> Should I really assume nothing is stable and keep
> trying to reload the API documentation before each request to the API
> that it describes?

You should assume that everything might change. It's a distributed system. You only control a very small part of it, namely the client. That doesn't mean you can't leverage caching though.


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

No. The URL still points to the Hydra ApiDocumentation, that doesn't mean that the representation you get back has to stay the same forever. New properties and new operations might be added at any time. That shouldn't break your client. Of course, removing thins you depend will break your client. Those changes should be minimized. But that has not much to do with what we are discussing here.


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

Cool. Thanks!



[1] https://github.com/HydraCG/Specifications/issues/71
[2] https://github.com/HydraCG/Specifications/issues/14


--
Markus Lanthaler
@markuslanthaler

Received on Wednesday, 17 September 2014 16:28:33 UTC