Improve documentation of the hydra:entrypoint property

[lanthaler]

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?

[alien-mcl]

Recent changes in the spec may make this issue outdated. While the hydra:Resource class still exists, it was removed from several ranges and domains. Also it's logic feels somehow different - it's a promise of a resource that can be dereferenced and having some of the classes defined in the hydra as sub-classes of hydra:Resource shouldn't imply that hose types are expected to be entrypoint(s).

[tpluscode]

I agree that we should not be too strict about this. The object of hydra:entrypoint would be anything that is dereferencable. Nothing less, nothing more.

While some resources, such as instances of hydra:Operation may have limited usefulness as API entrypoint resource, I would not discount the possibility for such design. Specifically, I can imagine an API to manage itself, where the root resource would be the hydra:ApiDocumentation itself.

By adding some restrictions here we may inadvertently close "legal" path for legitimate uses we would not predict

[alien-mcl]

I feel this issue is no more - closing it