RE: some more feedback

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.


>>> 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?
> 
> Well, what if I use both classes in a @type array and they describe
> the same property, and one says it is required and the other one says
> it isn't? What happens? I guess it resolves to required, but the spec
> might want to actually say so.

Good point. This is now ISSUE-73 [1]


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


>>> * 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.
> 
> Okay, this may be more about HTTP but I think it does relate to Hydra.
> Maybe you're proposing something like this:
> 
> We need to know whether the API documentation has become invalid. We
> need to know this so we can fetch it again from the server and then,
> say, regenerate a Python or JavaScript API. The Vary header could be
> used to invalidate the API documentation. (it'd not cover all cases;
> some other client you have no knowledge of may add permissions or take
> away permissions from you; this would never cause a change to your
> cookie)
> 
> If we write a custom client, we may have an API to the HTTP cache so we
> can check whether the cache for the API documentation URL was
> invalidated.
> 
> We need to do this check before each new interaction with the service
> described by the documentation, as in the mean time a permission may
> have been taken away from us. Or we could only do it whenever we
> actually get a HTTP error code from the service as I this is a signal
> our API documentation is out of date?

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.


> But what if we don't have such an API to the HTTP cache? Let's take a
> web browser -- do we have programmatic access to the browser cache? I
> don't think so, but I may be missing something.

Not sure why you would want that, you don't really need it because the browser takes care of it for us (as long as HTTP is used correctly). You can inspect the HTTP headers of the response though if it helps with your implementation.


> If not, I don't see how we can avoid doing another request of the
> documentation URL. The response may then come from the browser cache
> or go to the actual underlying service. We then need to detect whether
> the response was unchanged somehow, and we can't use a version number
> or timestamp as we're talking about permission-dependent differences.

You could use an ETag or the last-modified date.


> As far as I understand, we can't rely on the 304 status code as that
> only comes from the server -- and a 200 status code may in fact mean
> we get it from the cache.

Why do you need to know where it came from?


[...]

> But perhaps my assumption that API documentation on the client need to
> always up to date is incorrect, and we only refetch the API
> documentation when the server does not accept our request and returns
> a HTTP error. The HTTP error is the signal to us that our API
> documentation has become out of date and we need to refresh it.

That's what I would do in most cases. The alternative I explained in a previous mail is to change the URL of the ApiDocumentation in the HTTP link header on your responses.


>>> 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.
> 
> Let me try to describe it better.
> 
> If you have a RESTful client, it:
> 
> * doesn't have hardcoded knowledge about what URLs exist on the server
> except a single entry point. Related to this, doesn't have hardcoded
> knowledge about what types are expected from particular URLs.
> 
> * it follows links between resources to get to new resources.
> 
> * But it may still have hardcoded knowledge about the *types*. For
> instance, a web browser has hardcoded knowledge about what to do with
> the HTML type and the CSS type and the image type and the JavaScript
> type.
> 
> 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


Cheers,
Markus


[1] https://github.com/HydraCG/Specifications/issues/73


--
Markus Lanthaler
@markuslanthaler

Received on Wednesday, 1 October 2014 17:14:23 UTC