Re: More Feedback and Questions

On 10/11/2013 07:03 PM, Markus Lanthaler wrote:
> 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?
Considering section 4.3 it is clear and well described how to discover 
the entry point, yes.
But then it remains undefined what the a hydra aware client can to do 
with this information?
Say you have the supportedClasses as in your example below, how dies the 
client know under
which URL a collection of persons lives. The only way to bridge this gap 
I can think of is
that the client dereferences this entry point and gets a collection of 
resources:

{
   "@context": "http://purl.org/hydra/core/context.jsonld",
   "@id": "http://api.example.com/",
   "@type": "Collection",
   "members": [
     {
       "@id": "/persons/"
     }
     ...
   ]
}

Which in turn dereferences to a collection of persons.
Is that the intended use?

>
>
>> [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.
This is an interesting use case but what prevents you from re-using this 
class with a simple "@type": "http://schema.org/Person" on a resource 
and "hydra:expects": "http://schema.org/Person" on a collection?
>
>
> 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 19:28:19 UTC