Re: Specifying operations for instances

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. When the
spec is open to interpretation it will be possible that not every
client would be compatible with any Hydra server.

On Thu, Jun 19, 2014 at 12:27 AM, Markus Lanthaler
<markus.lanthaler@gmx.net> wrote:
> On 18 Jun 2014 at 23:58, Tomasz Pluskiewicz wrote:
>> The ApiDocumentation is described as similar to the documentation
>> developers would currently manually produce in natural language and as
>> such I assumed it wouldn't change unless the contract changed. Much like
>
> Well, if the ApiDocumentation changes, the "contract" changes.
>
>
>> traditional documentation wouldn't. That's the root of my confusion.
>> With that assumption in mind I couldn't understand how the client could
>> decide that some of the operations are actually "not available".
>
> Because the ApiDocumentation is *not* hardcoded into the client. It is interpreted at runtime. With the traditional, natural-language documentation that's impossible.
>
>
>> The idea of adjusting the ApiDocumentation representation sounds
>> interesting but a little bit awkward. Again, traditional documentation
>> wouldn't change so that developers can learn the API from written
>> text. Being in a machine-readible format is great but documentation is
>> still documentation. And ApiDocumentation is something else...
>
> Is it? Just because it's up to date? Also with current services you might get a different documentation if you log in as a "premium partner".
>
>
>> Also some operations are valid for a resource in a specific state.
>> Such operations will never be returned in the representation of
>> ApiDocumentation. Would it mean they are not supported?
>
> I thought we discussed this already!?
>
>
>> 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.

For that the client has to know something about the API. With
HAL/SIREN/Collection+JSON that something is rel="link name". That
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.

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.

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

>
> --
> Markus Lanthaler
> @markuslanthaler
>
>
>

Received on Friday, 4 July 2014 07:58:30 UTC