RE: More Feedback and Questions

On Friday, October 11, 2013 4:26 PM, kuno@frob.nl wrote:
> On 11.10.2013 12:19, Thomas Hoppe wrote:
> 
> >  3.) I really don't get the point about the "entrypoint" property.
> >  What is the semantics behind it?
> >  So far I consider it useless as it does not contribute to the URI
> > resolution (which was the only thing I could think of) --
> >  everything required for this is already specified here [1] I think.
> 
> My understanding is ...
> (and obviously I could be wrong :) 
> 
> Assuming a webservice at http://example.com/webservice/ with API
> documentation at http://example.com/doc/ .
> 
> There is no need to explicitly link [1] to the API documentation at
> /doc/ from the webservice responses, as you should end up there anyway
> if you resolve the classes and such from a /webservice/ response.
> 
> But if you start at http://example.com/doc/ , you can parse that and
> understand how to interact with the webservice being documented, but
> you do not know where that webservice is located unless
> http://example.com/doc/ has a hydra:entrypoint property pointing to it.

Exactly that's the reason. The other use case is to point from the normal website (www.example.com) to the API (api.example.com) using either an HTTP Link header or a <link> in the HTML header. I think section 4.3 of the spec [1] describes this quite nicely, doesn't it? 


> [1] to me it seems that hydra:apiDocumentation is rarely needed.
> Certainly the Hydra Console at
> http://www.markus-lanthaler.com/hydra/console/
> seems to be able to find the hydra:ApiDocumentation without it.
> 
> So I am curious to know what the use case for the
> hydra:apiDocumentation property is.

Yeah you are right. In principle everything also works without hydra:apiDocumentation but as explained above it might make sense to explicitly point to the API documentation so that machines can discover it. Another idea (which I'm not 100% sure of myself yet) was to allow to add information to concepts whose description isn't under the control of the API publisher.

If we would say that a client has to take into consideration the apiDocumentation when processing responses we could make it much simpler to reuse concepts from other vocabularies such as schema.org for instance. The client would look up the API documentation, would find a number of supportedClasses and trust the operations or supported properties associated to those classes. If that wouldn't be supported, it is necessary to introduce classes (e.g. subclasses or equivalent classes) to achieve that. Here's how you could associated some information to schema.org/Person in a ApiDocumentation:

{
  ...
  "supportedClasses": [
    {
      "@id": "http://schema.org/Person",
      "supportedProperties": [
         ...
      ],
      "supportedOperations": [
        ...
      ]
    }
  ]
}

Obviously, such information is just valid in the context of a single Web API. Matthias had a similar question some time ago [2] so perhaps we should clarify this in the spec. I've created ISSUE-13 [3] to keep track of this.


Cheers,
Markus


[1] http://www.markus-lanthaler.com/hydra/spec/latest/core/#discovering-a-hydra-powered-web-api
[2] http://lists.w3.org/Archives/Public/public-hydra/2013Jul/0004.html
[3] https://github.com/HydraCG/Specifications/issues/13


--
Markus Lanthaler
@markuslanthaler

Received on Friday, 11 October 2013 17:03:39 UTC