Re: Some Thoughts on Hydra Core

Hi,

I make an aggregated response here:
If the defined operations have, as you say, hardly a binding character and
every API provider is encouraged to define his own, specific operations
then I would agree to not having any operation on the spec or clearly 
marking them
as examples.

I still recommend however to resolve the CRUD wording issue.

Regarding the use case for a ReadResourceOperation, there is an obvious one:
If you want to specify the returned data structures with the
corresponding attributes for read operations in the API documentation, 
you need
this operation to specify this.

The sentence could read:
"Hydra is not limited to public APIs but can also be used on concert 
with an arbitrary
authentication solution. In hydra, the operations offered by a resource 
can be embedded in the representation
which allows to specify authentication constraints implicitly on a per 
request basis."

greets, Thomas

On 10/02/2013 08:33 PM, Markus Lanthaler wrote:
> On Monday, September 30, 2013 2:17 PM, Thomas Hoppe wrote:
>> Hi Markus,
>>
>> really sorry that I missed this one out.
>> Please see below my comments.
> No problem.. that's why we have an archive.
>
>
>>> On Friday, August 16, 2013 8:29 PM, Thomas Hoppe wrote:
>>>> Hello,
>>>>
>>>> I'm a intrigued follower of the efforts around Hydra.
>>>> Now the time has come to contribute my thoughts on some aspects:
>>>>
>>>> - "CRUD" stands by convention for
>>>> (http://en.wikipedia.org/wiki/Create,_read,_update_and_delete) for
>>>> Create,Read, Update, Delete while in the Spec "R" means Replace.
>>>> I recommend to stick to this convention. A replace operation is just
>>>> a special kind of "Update".
>>> That was a very deliberate design decision I made. While the first HTTP
> spec
>>> left the impression that the methods map 1:1 to the CRUD operations
> that's
>>> actually not true. HTTPbis [1] is a lot clearer in that regard. Therefore
> I
>>> decided to make the names of the predefined operations very explicit to
>>> encourage users to choose the right HTTP method for their operations. The
> U
>>> in CRUD can, e.g., be mapped to both PUT and PATCH.
>>>
>>> I would love to hear opinions about this from other people. To keep track
> of
>>> the discussion, I've created ISSUE-4 [2].
>> My point here was not the mapping to HTTP verbs, I want to _exclusively_
>> point out
>> the meaning of the acronym CRUD in general spoken language and I think
>> it's simply a bad idea
>> to deviate from this convention.
> Point taken, but, as I said further down in the mail you are replying to,
> those predefined operations are *only* there to help developers to get
> started. As such, I see them the first step to describe their (existing)
> APIs. If we would replace Replace with Update, the semantics of what
> actually happens would be lost. So, this is not an attempt to define the
> CRUD operations but to create something which allows developers to roughly
> describe what the various HTTP methods are doing. In most cases, those
> semantics are to weak anyway. It's a much better idea to define (and use)
> more specialized operations.
>
> Actually, I wouldn't opposed to remove those three predefined operations
> altogether but that would make it very difficult to describe this stuff IMO.
>
>
>>>> - There are formal Operations for modification operations
>>>> "CreateResourceOperation" etc. I'm opting for also having a
>>>> corresponding Read operation.
>>>> This is for example useful to advertise possible operations and might
>>>> also be useful for a formally sound integration with a AuthZ solution.
>>> My assumption was that if something is marked as being dereferenceable
>>> (i.e., it is marked as a hydra:Resource or the value of a hydra:Link) it
> is
>>> automatically considered to be readable. But you are right, it might make
>>> sense to also define something like a RetrieveResourceOperation. I've
>>> created ISSUE-5 [3] to keep track of this.
>>>
>>> Overall I have to say that those operations are more or less just to
>>> bootstrap very simple systems. In practice I expect people to define
> their
>>> own specialized operations because those predefined ones have extremely
> weak
>>> semantics.
>>>
>>> Does this makes sense to you?
>> Ok, I can comprehend your argumentation regarding the dereferencing
>> but still to interface with other solutions and standards a formal
>> description of "read" is sensible I think.
>> Think about standards like XACML, how would you express a relation to
>> a read operation if there is no such thing?
> I'm not a big fan of defining stuff in the hope that it will be useful
> later. You are right, as soon as we start talking about (simple) access
> control it may be necessary. Does that mean we have to define it now and put
> it in the core vocabulary? I don't think so.
>
>
>> I also think that this should be extensible but I think having the most
>> basic operations defined is also not a bad idea.
> Yeah, as Einstein already famously said: Make things as simple as possible,
> but not simpler.
>
> Let's try to look at this from a different angle. What use cases could be
> made possible by adding a ReadResourceOperation (and nothing else)? I
> couldn't come up with one and that's the reason why it's not there at the
> moment but it may very well be that I missed an important case.
>
>
>>>> - Authorization is a major concern and therefore I would also like to
>>>> see a chapter which describes how access to a hydra-driven API can can
>>>> restricted.
>>>> I think the obvious strategy is to "render" hydra-core documents with
>>>> only the operations which are allowed for by the requesting client.
>>>> This may sound natural but I think it is essential information for
>>>> someone exploring the matters.
>>> You are right, authorization is a major concern in any API. I
> intentionally
>>> left it out from the core vocabulary because I think this it is an
>>> orthogonal aspect which should be addressed separately. There also
> already
>>> exists a WebAccessControl vocabulary for that [6].
>>>
>>> Nevertheless, we should mention this in the spec and explain, e.g., that
>>> links might be hidden at runtime based on a user's permissions (as the my
>>> demo [7] does). As you may already have expected, I've created ISSUE-7
> [8]
>>> for this.
>> I'm fully with you, this topic should not be solved in the scope of hydra,
>> I only opt for a hint that this aspect is partly covered simply by
>> embedding affordances or not on a pre-request basis.
> Great. Do you have a concrete text in mind which we could include in the
> spec?
>
>
> Cheers,
> Markus
>
>
> --
> Markus Lanthaler
> @markuslanthaler
>
>

Received on Thursday, 3 October 2013 12:13:36 UTC