RE: Relating hydra:Classes to hydra:IriTemplates

On 23 Jun 2014 at 09:33, Jindřich Mynarz wrote:
> On Sun, Jun 22, 2014 at 10:14 PM, Markus Lanthaler 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.

Hmm... I wonder if the spec is the right place to do so. But we can certainly add a couple sentence to make this clearer. Concrete text proposals or even PR requests would be very helpful. At least to have something concrete to discuss and improve.


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

Perhaps you think a bit too much about this. Take a website at example. How many entry points does it have? Basically every page could act as an entry point as long as you are able to reach *every* other page from it. Does it make for you as a user to memorize multiple entry points? Most of the time it doesn't. Remembering the homepage is typically enough. If you are interested in a certain subsection of the website, however, it might make sense to remember it's URL and use it as your entry point. Similarly, the ApiDocumentation typically will have a single entry point. In some cases, however, it makes sense to give clients multiple entry points so that they can be more efficient (shorter paths to fulfil their goal).


> 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

Yeah, in a lot of cases that would be a sensible way to model the API.


> correct understanding? If it's fine to have multiple entry points,
> then I'd drop the "main" from the description of hydra:entrypoint.

As you see above, it may well be that there are multiple "main" entry points. In any case, we should clarify that in the spec as you suggest.



--
Markus Lanthaler
@markuslanthaler

Received on Monday, 23 June 2014 20:28:51 UTC