Re: Link relation types for non-GET links

[Klaus Hartke <[e-mail]>]

Mike Amundsen wrote:
> 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.

That's exactly what my initial question was about: should all
hypermedia controls take the shape of a link, with the link relation
types providing all the necessary details (like request method,
presentation, etc.), or should a media type provide a number of
syntactically different hypermedia controls so that the relation type
really only indicates the semantic meaning of the control.

The existence of the "edit" link relation type seems to point at the
former, although I would agree that it's probably better to keep it
separated and do the latter.

So, because I like HAL, I would extend HAL with forms, resulting in a
representation that might look like this:

  {
    "_links": {
      "terms-of-service": {
        "href": "http://example.org/tos",
        "type": "text/html"
      },
    },
    "_forms": {
      "create-a-new-item-in": {
        "href": "http://example.org/collection/",
        "method": "POST",
        "accept": "application/x-www-form-urlencoded",
        "fields": [ "firstName", "lastName", "eMail" ]
      }
    },
    ...
  }

The "create-a-new-item-in" non-GET link is kept separate from the
"terms-of-service" GET link, and has

* a context (a collection resource),
* a "form relation type" that enables a client to decide whether to
follow this link or not,
* a request method which indicates that following the link changes
resource state, is not safe and not idempotent, and
* a description of the payload that the server expects in the request
when following the link.

> 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 actually based that on H-Factor Link Support, except that I combined
LN and LI:

* link = LO (replaces the application state, safe [1], idempotent [2])
* embedding link = LE (adds to the application state, safe, idempotent)
* templated link = LT (replaces the application state, safe, idempotent)
* form = LN / LI (changes resource state, not safe, may or may not be
idempotent; includes the method to use, so the client would know if
it's idempotent or not)

(I'm not sure I understand what you mean by "mutability".)

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

The H-Factor page is actually printed and sitting on my desk :-)

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

Thanks, this looks interesting.

Klaus

[1] http://tools.ietf.org/html/rfc7231#section-4.2.1
[2] http://tools.ietf.org/html/rfc7231#section-4.2.2