Re: Link relation types for non-GET links

[Erik Wilde <[e-mail]>]

hello klaus.

On 2015-08-15 08:21, Klaus Hartke wrote:
> Erik Wilde wrote:
>> not any more than it would make sense to have a generic GET relation type
>> that says "read"...
> The most common type of links in the web are simple <a href=""></a>
> links that could be interpreted as having a "read" relation type.

it's more a <html:a> relation type: it's an assertion the HTML author is 
making about the link source. and while none of the "implicit link 
relation types" (see my previous email) are registered as "explicit IANA 
link relation types", it still makes a lot of sense to look at them as 
being their own distinct ways how to interlink resources.

> IMO it makes sense to provide one link per action rather than
> providing a single "edit" link, because some actions might be invalid
> for the current state of the resource, or the user might not be
> authorized to perform all actions.

i think julian answered the general question well. however, i do agree 
with you that some designs could benefit from having runtime 
information. for example, while a general paging link could tell you 
that you can use a page number as parameter, at runtime it could be nice 
to let the client know that according to current resource state, there 
are 42 pages available. the UI then can reflect that.

this is the exact reason why 
https://github.com/dret/I-D/tree/master/link-desc exists: it should 
allow resources to embed runtime information, so that clients get more 
information than without it. of course, once the client sends the 
request, the 42 pages hay now be 41 or 43, and that's still something 
the client should be prepared to handle. but still, in some scenarios, 
UI design wants to show that "currently, there are 42 pages", and then 
runtime info is required.

>> defining a general-purpose format that captures all possible ways in which
>> link relations may have rules associated with them is hard, and personally,
>> my link description mentioned above draft has stalled because without a
>> better picture of what should and shouldn't be covered, this is a typical
>> "designing into the void" scenario.
> I'm not trying to design something; I'm trying to collect best
> practices. However, while safe links seem to be well understood, there
> does not really seem to be consensus on how hypermedia controls for
> manipulating resource states should look like.

the reason for this, in my opinion, is that people do this more on an 
ad-hoc basis. HTML forms are a good example, they do it (allowing 
GET/POST and defining URI parameter encoding), but in a way that's hard 
to reuse outside of HTML. 
https://github.com/dret/I-D/tree/master/link-desc is an attempt to turn 
this into a reusable model, but like i said in an earlier email, it's 
not easy to get right because there's a much greater variety of 
information that people might want to represent than with simple 
read/GET links.

> Based on what I've seen so far, to me it seems that such a hypermedia
> control is modelled best like safe links with the following
> information:
> * an identifier identifying the semantics of the hypermedia control
> (the relation type),
> * the subject of the hypermedia control (i.e., the resource that is
> being manipulated, the context), and
> * enough information for the client to construct a request to
> manipulate the resource, which includes
>         - the request method to use,
>         - the request URI to use, and
>         - a machine-readable description of the payload to include in
> the request.

feel free to cross reference this against 
https://github.com/dret/I-D/tree/master/link-desc. yes, media type would 
be good (a la Accept-Post), but then also URI template support, but 
there you also need to add some information about what the variables are 
supposed to represent.

to me, there's a good reason why this has been done ad-hoc and mostly in 
documented (and not completely machine-readable) form. it's the 
complexity of the design space. make it too simple and it's not 
expressive enough. make it expressive enough and it might become too 
cumbersome for most simpler use cases.

> So the major difference between a safe link and an unsafe one is the
> non-GET request method and the description of the payload. I don't
> think that a lot more than this is needed.

what about URI templates? those were very high up in the list of things 
we needed (see the "page number of paged collection" example above).

> (Background: people are looking for advice on how to build
> applications on top of CoAP [1]. I've started to collect some best
> practices in a draft [2], and made an attempt at defining some
> terminology for hypermedia controls [3]. The idea is, if we cannot
> provide advice for RESTful Web APIs in general, maybe it's possible to
> establish consensus on how RESTful Web APIs in constrained
> environments [4] should look like.)
> [1] https://tools.ietf.org/html/rfc7252
> [2] https://tools.ietf.org/html/draft-hartke-core-apps-01
> [3] https://tools.ietf.org/html/draft-hartke-core-apps-01#section-2.4
> [4] https://tools.ietf.org/html/rfc7228

interesting. it might be interesting to cross-check [3] with 
https://github.com/dret/hyperpedia/blob/master/concepts.md, which might 
have very similar goals. for hyperpedia, i have also started collecting 
formats (https://github.com/dret/hyperpedia/blob/master/formats.md), but 
still need to go through that list and see what kind of concepts the 
individual formats are supporting.

do you see anything missing from hyperpedia concepts that you think 
matters for your scenario? if so, please submit an issue, so that i can 
make sure that the concepts are as comprehensive as possible.

thanks and cheers,

dret.

-- 
erik wilde | mailto:[e-mail]  -  tel:[phone] |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |