RE: Specifying operations for instances

On 4 Jul 2014 at 09:57, Tomasz Pluskiewicz wrote:
> I'm currently coming to terms with what Markus is repeating in the
> sense that Hydra is intended to be flexible and that is a good thing.
> 
> However I fear that this flexibility can come with a price.

It definitely comes at a price, namely implementation complexity.


> When the
> spec is open to interpretation it will be possible that not every
> client would be compatible with any Hydra server.

This is definitely not what I would call flexibility but a spec bug that has to be fixed.

More below:

> On Thu, Jun 19, 2014 at 12:27 AM, Markus Lanthaler:
>> On 18 Jun 2014 at 23:58, Tomasz Pluskiewicz wrote:
>>> Come think of it now I would probably have modelled this part of Hydra
>>> differently so that the assumption about ApiDocumentation is that it
>>> contains all possible operations the API defines. These operations would
>>> have been identified resources so that they can be dereferenced. And
>>> then instances could reference them by URI or add their own additional
>>> operations.
>> 
>> That approach is fully supported by the current design.
>> 
> 
> You're right. I mix dereferencing an operation with including it in
> ApiDocumentation. These are two separate things. An ApiDocumentation
> could also only contain a reference and not the whole representation.
> 
>> 
>>> However in such model all operations would have to be
>>> decalred or referenced in the resource's representation.
>>> ApiDocumentation would be just that - documentation. One from which a
>>> developer can get a bigger picture and a centralized repository of API
>>> metadata.
>> 
>> That's the difference. The ApiDocumentation is not really intended for the
>> developer. It is for the client. The last thing that I as a developer want to do is
>> to read documentation. If a machine can do it for me, let the machine do it.
>> There are much more important and interesting things for me to do.
> 
> I don't fully agree. Most clients are not going to be generic and
> autonomous clients IMHO. If I want to render UI based on hydra:Links
> and hydra:Operations I want to be able to tell one from another so
> that I can organize them visually in my design. It's not as simple as
> iteration over every possible option and generating some forms/links.

Fully agreed. (Almost) all hydra:Links will be unambiguously identified with an IRI, so no problem there. Operations on the other hand should be typed as otherwise, as you rightly point out, there's too little information for a client. For *some* operations it might even make sense to give them a IRI.


> For that the client has to know something about the API. With
> HAL/SIREN/Collection+JSON that something is rel="link name". That

Please note that in principle is exactly the same with Hydra. The only different is that "link name" will *always* be a IRI, i.e., there exist no special cases (string tokens) just because they have been added to a central registry, i.e., the IANA link relation registry [1].


> defines the contract and the client will look for specific values.
> Unrecognized link and operation could either be ignored or added in a
> generic way as fallback.

This is where Hydra goes a step further because it allows you to describe that contract in a machine readable way.


> With links it's simple, because the hydra:Link predicates define that
> contract. I don't think there is a way for clients to distinguish known
> operations currently. I'd like to start a new discussion about that.

Yes, there is. You type the operations, i.e., you say that an operation is of type CreateResourceOperation (please note: we are probably removing this type) or, e.g., choose one of the many Action subtypes of schema.org [2] (scroll down).


> Coming back to ApiDocumentation, I think it what the developer would use
> to discover the links/operation that need special care on the client.
> Hence my previous assumption that ApiDocumentation always contains all
> operations (not taking sth like Premium access into account).

OK, that's actually a very good point. Perhaps we should add a mechanism to enumerate the supported operation types and properties (or just links?) directly to ApiDocumentation similar to how it enumerates the supportedClasses. I've created ISSUE-59 to track it.


[1] http://www.iana.org/assignments/link-relations/link-relations.xhtml
[2] http://schema.org/Action
[3] https://github.com/HydraCG/Specifications/issues/59


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 7 July 2014 16:21:19 UTC