Re: Link relation types for non-GET links

[mike amundsen <[e-mail]>]

Klaus:

I think an important design decision is whether you want to overload a link
rel value ("edit", "item", "collection", "payment") with protocol-level
information like "idempotent", "safe", etc. or rendering information like
"transclude", "immutable:, etc.

My advice is to keep them separate.

Your definitions in 2.4 are a bit unclear (by my reading)
_link_ promises "navigation" ("transclude=false") but does it also promise
"safe=true"?
_embedded_link_ promisses "transclude=true" but does it also promise
"safe=true"?
_templated_link_ promises "mutability" but what of safety and transclusion?
_form_ is promising "safe=false" but some are idempotent, some not.

esp. when working with automated systems, you'll need to sort this out
explicitly -- preferably inband, i suspect.

i wrote up a draft paper in 2011 that talks about these[1] "hypermedia
aspects" (safety, idempotence, mutability, and transclusion) and have a web
page that lists the most common hypermedia factors[2] (that page could use
some "love", tho <g>).  This might help you in designing a media type that
does a good job supporting a wide range of protocol-agnostic actions and
promises.

Finally, I am working on a media type design specifically aimed at
automated agents -- Uniform Basis for Exchanging Representations (UBER -- I
know...)[3] that you are free to use that for inspiration, caution, etc.

cheers



[1]
http://www.w3.org/2011/10/integration-workshop/p/hypermedia-oriented-design.pdf
[2] http://amundsen.com/hypermedia/hfactor/
[3] http://uberhypermedia.com





mamund
+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

On Sat, Aug 15, 2015 at 11:14 AM, Klaus Hartke <[e-mail]> wrote:

> Julian Reschke wrote:
> > The link relation by definition can not be "unsafe".
>
> Ah, terminology. I meant to say that there are links with link
> relation types that indicate that the client should use a method other
> than GET when following the link ("non-GET link" for short). If these
> have the same syntactic form as "GET links" in a representation, and a
> spider does not know the link relation type, the spider does not know
> which method to use to follow the link. However, if they have distinct
> syntactic forms, a spider could at least follow the "GET links", even
> without understanding the link semantics in detail. This seems to be a
> useful feature.
>
> (BTW, there is a section titled "Unsafe Link Relations" in the RESTful
> Web APIs book [1].)
>
> > The link is always safe; it's the method applied to the link target which
> > might not.
>
> Maybe it's then a good idea to find better terms than "safe" and
> "unsafe" (or "GET" and "non-GET") to refer to different types of
> links. I hope we can agree that there are two types of links:
>
> - Links that cause a transition in the client-side application state
> when followed, and
> - Links that cause a transition in the server-side resource state when
> followed.
>
> I'm calling these "links" and "forms" in my draft [2], respectively,
> but I'm happy to switch to other terms if there is consensus on how
> they should be called.
>
> Klaus
>
> [1] http://restfulwebapis.com/
> [2] https://tools.ietf.org/html/draft-hartke-core-apps-01#section-2.4
>
> _______________________________________________
> link-relations mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/link-relations
>