RE: Relating hydra:Classes to hydra:IriTemplates

On 19 Jun 2014 at 12:04, Jindřich Mynarz wrote:
> On Wed, Jun 18, 2014 at 11:12 PM, Markus Lanthaler wrote:
>>> Nothing particularly bright comes to my mind, but maybe a sentence like
>>> "An entry point is a dereferenceable resource that provides links to
>>> access the API." can be added after the first sentence of the section
>>> 4.3
>>> (http://www.hydra-cg.com/spec/latest/core/#discovering-a-hydra-powered
>>> - web-api).
>> 
>> Hmm... honestly I find this a bit confusing. It gives the impression that an entry point is
> some intermediary node between the API documentation and the API itself. That's however
> not true. It is already part of the API. Actually, I find the spec is already quite clear about it:
>> 
>>   "The first step when trying to access a Web API is to find an entry point..."
>> Do other people find the concept of an entry point difficult to
>> understand? What about the description thereof in the specification?
>> 
>>   http://www.hydra-cg.com/spec/latest/core/#discovering-a-hydra-powered-web-api
> 
> Well, as I said in my previous email, I don't find the description
> I've provided to be particularly well-phrase.
> 
> Let's look at it this way. The rdfs:range of hydra:entrypoint is defined
> to be hydra:Resource. Hydra describes several sub-classes of
> hydra:Resource:
> 
> hydra:ApiDocumentation
> hydra:Collection
> hydra:IriTemplate
> hydra:IriTemplateMapping
> hydra:Operation
> hydra:StatusCodeDescription
> hydra:SupportedProperty
> 
> Judging just from the RDF description of Hydra, each of these
> sub-classes can be used in the range of hydra:entrypoint, however, it

Fair enough


> clearly doesn't make sense to do so for several of these sub-classes
> (e.g., hydra:IriTemplateMapping). Further disambiguation is thus left
> to the description in Hydra's specification, where I can't find any
> suggestion what classes are typically used as entry points. The reader
> is left wondering if for instance hydra:IriTemplate or
> hydra:Collection are fine to be used as API entry points.

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.


> I think that even better than describing it in plain-text would be to
> have at least one example in the shape:
> 
> :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.


>>> If you don't embed the </users/> hydra:Collection in the </> resource,
>>> then you'd still need to dereference it first to discover that offers
>>> a search functionality.
>> 
>> Yes, but is it a problem to embed it there? I do understand that you might want to keep
> this cleaner. I just want to understand whether there are any technical drawbacks.
> 
> 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.


>>> I'd rather have a way to enable clients to
>>> discover such functionality (also) via hydra:ApiDocumentation and
>>> hydra:supportedClass. Is the following pattern, which I have used in
>>> my previous questions as well, violating some assumptions in Hydra?
>>> 
>>> :api-documentation a hydra:ApiDocumentation ;
>>>   hydra:supportedClass :Class .
>>> :Class hydra:search :search-iri-template .
>> 
>> No, but it is currently undefined how a client should interpret that information. I have to
>> say, I quite like this idea even though it might promote tight coupling.
> 
> 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.


[1] https://github.com/HydraCG/Specifications/issues/52



--
Markus Lanthaler
@markuslanthaler

Received on Sunday, 22 June 2014 20:15:05 UTC