RE: profile link relation

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).


[1] http://www.w3.org/TR/json-ld/#iana-considerations



--
Markus Lanthaler
@markuslanthaler

Received on Sunday, 25 August 2013 18:55:41 UTC