Re: profile link relation

On Sun, Aug 25, 2013 at 8:55 PM, Markus Lanthaler
<markus.lanthaler@gmx.net>wrote:

> On Friday, August 23, 2013 7:18 PM, Arnau Siches wrote:
> > Hi folks,
> >
> > What do you think about using the 'profile' link relation
> > type [RFC6906] to define the API entry point? At first
> > glance it seems like the apiDocumentation as relation type
> > (Hydra spec, section 4.3).
> >
> > So
> >
> >    Link: <http://api.example.com/doc/>;
> >          rel="http://purl.org/hydra/core#apiDocumentation"
> >
> > would be
> >
> >    Link: <http://api.example.com/doc/>; rel="profile"
>
> The profile link relation is used to specify additional constraints,
> conventions, or extensions a representation adheres to. In the context of
> JSON-LD that could, e.g., be used to signal whether the document is in
> expanded form or not. That's also the reason why JSON-LD has a profile
> media type parameter [1].


> I think linking to a Hydra description documentation is something entirely
> different. It doesn't have much to do with the current representation you
> are looking at. I wanted to have a very specific link relation so that
> publishers could link to the API description form everywhere.
>
> Let's say you run the website www.example.com and have an API at
> api.example.com. In that case it wouldn't make much sense to tag
> responses from www.example.com with a profile link. On the other,
> including an apiDocumentation link would make a lot of sense IMO. That way,
> the API can be discovered even if a client is pointed to the normal
> homepage. You could for example write a browser plugin which signals the
> discovery of a Hydra-described API and then launch the Hydra console
> (that's actually something I planned to create as a browser plugin).
>

Alright, I was thinking all the time in using the 'profile' link to tag
resources of the API. The spec is clear about that. My mistake.


What I said was based in (quoting RFC6906):

   As one example, consider the case of podcasts, where a specific kind
   of feed uses additional fields for media-related metadata.  Using a
   'profile' link, it would be easily possible for clients to understand
   that a specific feed is supposed to be a podcast feed, and that it
   may contain entries using podcast-specific fields.


Which, if I'm correct, overlaps with the `@context` intention. Is it?


Just to make sure, the `apiDocumentation` link it's intended to be used
primarily to discover the API (through its documentation) from the outside
whereas the `@context` in each API resource is enough
description/explanation to know how a field should be handled.



-- 
Arnau Siches
@arnau_siches