RE: Some Thaughts on Hydra Core

OK, the W3C webmaster looked in to this issue and manually approved Thomas'
mails. That's why you all got them now again twice. I hope we won't have
similar issues in the future as normally W3C's mailing lists work quite
well.

Comments inline below


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


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


> - A typo "is be defined to"

Fixed [4], thanks for reporting it.


> - Sorting of paged collections should be specified and examplified
> which is not the case yet.

I tried to keep the Hydra Core vocabulary as small as possible while still
keeping it useful by itself for at least simple applications. It's always
difficult to find the right tradeoff but IMO sorting of paginated
collections is clearly an advanced feature which shouldn't be put in core.
Sorting criteria can quickly become quite complex and is better handled in a
separate specialized vocabulary. That doesn't mean that it has to be a
separate namespace but I wanted to keep the core spec as small and simple as
possible.

I envision Hydra as being a set of modular vocabularies (which quite
possible share the same namespace). Other things may start to outside of
Hydra and are then pulled in after their utility has been shown in practice.
Other than not being able to display the sorting criteria, what use cases
are prevented by the fact that the sorting isn't specified?

Btw. this is now ISSUE-6 [5] :-)


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


> Keep up the good work,
> Thomas

Thanks for the very useful feedback and joining the CG. All of these are
very reasonable concerns and should be discussed as a group. So don't see my
comments as definitive answers but just as my positions in a discussion.. so
feel free to challenge them :-)


Cheers,
Markus


[1] http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-23#section-4
[2] https://github.com/HydraCG/Specifications/issues/4
[3] https://github.com/HydraCG/Specifications/issues/5
[4]
https://github.com/HydraCG/Specifications/commit/88feb006ef885cded177eabe385
b72cb467d50d1
[5] https://github.com/HydraCG/Specifications/issues/6
[6] http://www.w3.org/wiki/WebAccessControl
[7] http://www.markus-lanthaler.com/hydra/
[8] https://github.com/HydraCG/Specifications/issues/7



--
Markus Lanthaler
@markuslanthaler

Received on Saturday, 17 August 2013 17:59:51 UTC