RE: More Feedback and Questions

On Friday, October 11, 2013 9:28 PM, Thomas Hoppe wrote:
> On 10/11/2013 07:03 PM, Markus Lanthaler wrote:
> > On Friday, October 11, 2013 4:26 PM, kuno@frob.nl wrote:
> >> 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?

It's similar to a website. You should design your API in a way so that it is possible to reach every resource by starting at the main entry point (homepage). In the Issue tracker demo on my homepage [1] I introduced a separate concept for that (EntryPoint) that has various properties that link to the various things (issues, users, registration link).


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

Yeah even though I would design it slightly different. I would create a concept like EntryPoint and a number of properties (aka link relations) which a client can use to find its way to the desired resource.


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

Could you please describe the alternative in a bit more detail. I don't think I understand what you mean.

You can of course say that you expect a schema.org/Person in an operation but that's not enough to tell a client what properties are meant because looking up schema.org/Person doesn't give you that information. Since you don't have control over schema.org, you also can't change that. So we either need to define our own specialized class or we associate the properties to be used with that specific class *in the context of our API*.


Cheers,
Markus

[1] http://www.markus-lanthaler.com/hydra/


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 14 October 2013 14:44:31 UTC