Re: Relating hydra:Classes to hydra:IriTemplates

On Sun, Jun 22, 2014 at 10:14 PM, Markus Lanthaler
<markus.lanthaler@gmx.net> wrote:
> The issue here is that it is quite difficult to answer this question as it depends on what the service is doing. But I see your point.

This is why I think that, instead of enumerating classes that are
recommended to be used as entry points, it would be more useful if
Hydra specification had a few examples of entry points, so that the
readers can see the "entry point classes" being used in fitting
context.


>> :api-documentation a hydra:ApiDocumentation ;
>>   hydra:entrypoint :entry-point .
>> :entry-point a :Class .
>>
>> Where :Class would be an example of recommended class for an entry point.
>
> Good idea. What about using an example wit hydra:Collection and mentioning that the other subclasses of hydra:Resource *typically* don't make that much sense? I've created ISSUE-52 [1] to track this.

Hydra describes hydra:entrypoint as "a link to main entry point of the
Web API", which hints that there's likely a single main entrypoint for
an API (i.e., hydra:entrypoint is sort of owl:FunctionalProperty). If
an API supported multiple classes, then I'd presume it should expose a
hydra:Collection for each of these classes, and each of these
collections should be linked to via hydra:entrypoint. Is that a
correct understanding? If it's fine to have multiple entry points,
then I'd drop the "main" from the description of hydra:entrypoint.


>> No, I don't see any technical drawbacks of embedding the descriptions
>> of collections directly in an API entry point. The only drawback is
>> duplication of the description of collection in the representation of
>> entry point and its own representation.
>
> Well, putting it in the ApiDocumentation would be the same duplication.

Fair point. I guess you can either pick duplication or more "chatty"
interaction with more requests.


>> Why do you think it might promote tight coupling in contrast to the
>> other approaches?
>
> Because the API documentation is typically seen as something that doesn't change very often (there was a related discussion in a related thread a couple of days ago). If there's enough information in the API documentation, it becomes too tempting for developers to use this information for, e.g., code generation which then hardcodes this information into clients. Obviously this tightly couples the clients to the server and such clients will break whenever the ApiDocumentation (that they aren't interpreting at runtime anymore) changes.

Ok, thanks for elaborating your point.

- Jindřich

-- 
Jindřich Mynarz
http://mynarz.net/#jindrich

Received on Monday, 23 June 2014 07:34:41 UTC