Subject: Link relation types for non-GET links

From: Klaus Hartke <[email-masked]>
Date: Thu, 6 Aug 2015 14:33:04 +0200

Hi link relation type experts,

I'm using links in my application to discover resources, and link
relation types to indicate the semantics of a link. Now I'm stumbling
on links that change the resource state when followed (i.e., links
that cause requests with methods other than GET).

RFC5988 says that link relation types "can specify the behaviours and
properties of the target resource (e.g., allowable HTTP methods,
[...])."

However, none of the registered link relation types seems to do this.
My question is: Have link relation types for non-GET links simply not
been registered yet, or should a non-GET link perhaps be a different
hypermedia control?

For example, let's say I have a collection resource and want to
provide a way for clients to add new collection items. So I would add
a POST link that, when followed, creates the new item and updates the
collection. What should the link relation type be in
"http://example.org/collection has a ??? resource at
http://example.org/collection"?

  {
    "_links": {
      "terms-of-service": {
        "href": "http://example.org/tos",
        "type": "text/html"
      },
      "???": {
        "href": "http://example.org/collection/"
      }
    }
  }

  (using HAL-like syntax [1])

Or should I add the equivalent of an HTML form to my media type, and
have a "form relation type" (for the lack of a better term) to
identify the semantics? This would allow me to make statements of the
form "To {relation type} the {context IRI}, make a {method} request to
{target IRI}", e.g., "To create-a-new-item-in the
http://example.org/collection, make a POST request to
http://example.org/collection".

  {
    "_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" ]
      }
    }
  }

Would it make sense to have a registry for common form relation types?

Best regards,
Klaus

[1] https://tools.ietf.org/html/draft-kelly-json-hal-07

---

From: mike amundsen <[email-masked]>
Date: Thu, 6 Aug 2015 09:27:20 -0400

the IANA reg'd values "edit" and "edit-media" support unsafe (non-GET)
actions and are documented in RFC5023[1].

[1] http://tools.ietf.org/html/rfc5023#section-11

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 Thu, Aug 6, 2015 at 8:33 AM, Klaus Hartke <[email-masked]> wrote:

> _______________________________________________
> link-relations mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/link-relations
>

---

From: Klaus Hartke <[email-masked]>
Date: Thu, 13 Aug 2015 14:03:09 +0200

> actions and are documented in RFC5023[1].

So, is that the preferred way of doing things? Would it make sense to
register a bunch of generic non-GET link relation types, like
"create", "execute", "update", "delete"?

It seems the syntax for links in RFC5988 and HAL needs to be extended
for non-GET links to include a description of the representation that
the service accepts when following the link (e.g., accepted media type
and/or a set of form fields).

How does a spider distinguish between safe links and unsafe non-GET links?

Klaus

---

From: Julian Reschke <[email-masked]>
Date: Thu, 13 Aug 2015 14:22:53 +0200

> How does a spider distinguish between safe links and unsafe non-GET links?

A spider is not supposed to use methods other than GET, so how is this a 
problem?

---

From: Erik Wilde <[email-masked]>
Date: Thu, 13 Aug 2015 18:11:11 -0400

hello klaus.

> "create", "execute", "update", "delete"?

not any more than it would make sense to have a generic GET relation 
type that says "read"... link relation types should primarily indicate 
why somebody would want to follow a link. in HTTP-land, that may 
sometime require using methods other than GET, so that the uniform 
interface is used correctly. if so, the link relation definition (or the 
service making use of it) should say so, so that clients know how to 
engage in the interaction.

> and/or a set of form fields).

that get's rather complicated rather quickly. it has been attempted a 
couple of times, including by myself...

https://github.com/dret/I-D/tree/master/link-desc

the problem is where to draw the line, and that is hard to do outside of 
specific scenarios. for example, for W3C's LDP a simple HTTP header 
field did the trick (instead of embedding that info into the payload), 
so that's what they are using:

http://www.w3.org/TR/ldp/#header-accept-post

but that's quite a bit more limited what you seem to have in mind. 
however, 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.

cheers,

dret.

-- 
erik wilde | mailto:[email-masked]  -  tel:+1-510-2061079 |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |

---

From: Mike Kelly <[email-masked]>
Date: Fri, 14 Aug 2015 08:07:31 +0100

Hi Klaus,

You can use a standard HAL link and a link relation if you ensure the link
relation is a URL which can be dereferenced to retrieve a machine-readable
description of the methods and messages that are possible for that link.
Just think of it as machine readable link relation documentation.

Cheers,
M

Sent from my mobile

---

From: Klaus Hartke <[email-masked]>
Date: Sat, 15 Aug 2015 14:16:48 +0200

> A spider is not supposed to use methods other than GET, so how is this a

If the spider does not know the link relation type, it will assume
that there is a safe link between the two resources even when the link
relation type defines the link to be unsafe. But maybe that's not a
big problem.

It's just that HTML defines a number of syntactically different
hypermedia controls (<a>, <img>, <form>), so a spider can understand
whether the link is safe or not even if it does not recognize the link
relation type.

Klaus

---

From: Julian Reschke <[email-masked]>
Date: Sat, 15 Aug 2015 14:21:18 +0200

> relation type defines the link to be unsafe. But maybe that's not a

The link relation by definition can not be "unsafe".

> whether the link is safe or not even if it does not recognize the link

The link is always safe; it's the method applied to the link target 
which might not.

Best regards, Julian

---

From: Klaus Hartke <[email-masked]>
Date: Sat, 15 Aug 2015 14:21:55 +0200

Erik Wilde wrote:
>> Would it make sense to
> 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.

> link relation types should primarily indicate why
> somebody would want to follow a link. in HTTP-land, that may sometime
> require using methods other than GET, so that the uniform interface is used
> correctly. if so, the link relation definition (or the service making use of
> it) should say so, so that clients know how to engage in the interaction.

Right. For example, if you have a collection resource, you might want
to provide a link that, when followed, creates a new item in the
collection. Or each item might have links to update or delete the
item:

  <tasks>
    <link rel="create" href="/tasks" method="POST"
accept="application/task+xml application/task+json"/>
    <task id="t1">
      <description>Take out the trash.</description>
      <link rel="update" href="/tasks/1" method="PUT"
accept="application/task+xml"/>
      <link rel="delete" href="/tasks/1" method="DELETE"/>
    </task>
    <task id="t2">
      <description>Pick up the kids.</description>
      <!--readonly-->
    </task>
    <task id="t3">
      <description>Return books to the library.</description>
      <link rel="update" href="/tasks/3" method="PUT"
accept="application/task+xml"/>
    </task>
  </tasks>

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.

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

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.

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.

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

Klaus

[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

---

From: Klaus Hartke <[email-masked]>
Date: Sat, 15 Aug 2015 14:27:33 +0200

> Just think of it as machine readable link relation documentation.

That's an interesting idea. It basically adds a level of indirection,
which should be useful if many links have the same machine-readable
description of possible methods and payloads. However, I think I'd
prefer including that description directly at the link, so a client
does not have to dereference a URL to understand the link semantics.

Klaus

---

From: algermissen1971 <[email-masked]>
Date: Sat, 15 Aug 2015 15:03:18 +0200

Klaus,

you are trying to mix "resource semantics" with "runtime information".

Links (any form of hypermedia for that matter) tell the user agent whatthe nature of the resource is ("A feed of entries" , "a resource that supports search", "a product catalog","a product details page", "an index"..)

REST deliberately decouples resource semantics from any runtime specifics (e.g. which method does a resource support at any given point in time). The consequence is that a specification of a link relation can never actuallt constrain meaningfully a server  to any specific runtime behavior. Link relation specs can provide *hints* for implementors what make sense to support, but these can only ever be just that: hints. The client must deal with what happens at runtime anyway.

Sometimes it can help to provide explicit runtime deatils about the method (think about HTML forms' "action" attribute), but frankly, separate syntax constructs (==link relation types) are usually better (after all, a resource that supports indexing into (GET form) is very different from a resource that you can submitt stuff to (POST form).

Ususally (if not allways) you will find that making the supported method design time information (specs) rather than runtime information seems necessary at first, but when it comes to putting the method in the client request code, it will be obvious anyway, which of the handfull of methods to use.

And if the clients sends a PATCH and the server at runtime does not deliver on whatever promise a spec made - what's the spec going to help? The client must figure out the method to use from the response headers anyhow, or apply common sense and retry with the POST ... or give up and hand the issue to a human for resolution.

(REST does not magically solve the contract issues of decentralized systems, it just prescribes very explicitly the places where they surface at runetime - do not constrain at design time what makes no sense to constrain enyway).

HTH,

Jan

On 15 Aug 2015, at 14:21, Julian Reschke <[email-masked]> wrote:

> The link is always safe; it's the method applied to the link target which might not.
> 
> Best regards, Julian
>

---

From: Mike Kelly <[email-masked]>
Date: Sat, 15 Aug 2015 14:05:10 +0100

Fair enough. It's worth bearing in mind the cache lifetime of the link rel
descriptions are likely to be relatively high compared to the resources
themselves; so the indirection could potentially reduce the size of the
responses as well as metadata noise in the responses.

But if you need/want this information inline, then you can attach it as a
properly to the given link object.

Cheers,
M

-- 
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

---

From: Erik Wilde <[email-masked]>
Date: Sat, 15 Aug 2015 09:53:22 -0400

hello klaus.

> whether the link is safe or not even if it does not recognize the link

http://dret.typepad.com/dretblog/2009/10/links-in-html.html is where 
just out of curiosity i tried to list all of the link types that are 
defined by HTML. but keep in mind that from a logical perspective, these 
are all "link relation types" (except for <link>, which supports and 
requires runtime typing): each of those elements defines a certain kind 
of relationship between the HTML page and a referenced resource, and 
spiders (and other clients) decide based on this relationship whether 
they want to follow a certain link or not.

cheers,

dret.

---

From: Erik Wilde <[email-masked]>
Date: Sat, 15 Aug 2015 10:09:14 -0400

hello klaus.

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

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

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

>         - a machine-readable description of the payload to include in

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.

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

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

---

From: Erik Wilde <[email-masked]>
Date: Sat, 15 Aug 2015 10:13:36 -0400

hello mike and klaus.

> does not have to dereference a URL to understand the link semantics.

if you have a standalone format (such as 
https://github.com/dret/I-D/tree/master/link-desc or whatever you come 
up with to represent link interaction information), then embedding it or 
making it external or allowing both is a simple design choice and flip 
for anybody using it.

our main driver for allowing this kind of flexibility was the scenario 
mentioned before: the general link relation type might define a number 
of parameters clients can submit, but the specific runtime info could be 
more constrained ("only 42 pages you can GET"), and clients could adjust 
accordingly. ideally, there would be some kind of "inheritance model" 
(effective link interaction semantics are a combination of the generic 
ones, and runtime info can selectively overwrite), but we never got far 
enough to really have a well-defined model for that.

cheers,

dret.

---

From: Klaus Hartke <[email-masked]>
Date: Sat, 15 Aug 2015 17:14:24 +0200

> 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

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

---

From: mike amundsen <[email-masked]>
Date: Sat, 15 Aug 2015 11:47:15 -0400

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

---

From: Klaus Hartke <[email-masked]>
Date: Sat, 15 Aug 2015 19:56:23 +0200

> 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": {
    ...
  }

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.

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

> does a good job supporting a wide range of protocol-agnostic actions and

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

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

---

From: Erik Wilde <[email-masked]>
Date: Sat, 15 Aug 2015 14:05:12 -0400

hello klaus.

On 2015-08-15 13:56, Klaus Hartke wrote:
>> "transclude", "immutable:, etc. My advice is to keep them separate.

you can go both ways, and different people have different opinions. my 
meta-opinion is that there is no "right way" of doing it, and my 
meta-guidance is to at least always be consistent in the set of services 
or media types you're designing.

my non-meta-opinion is like mike's: keep the link relations general and 
generic, just specific enough so that hypermedia controls can be 
identified in representations. then design the representation to provide 
all the details that your scenario might need. here's my reasoning:

- this way you keep the existing/registered link relations to a minimum, 
by not assuming that every little piece of information is implied in the 
link relation type. instead, that's the job of the link's context and 
can be adjusted as needed.

- this way you also can make certain mechanisms (such as the link 
descriptions i am working on) reusable, so that they can be used for 
*any* kind of link relation type where you might want to use them.

to me, this is a question of separation of concerns, but i have had long 
discussions with that with people leaning the opposite direction.

like i said, the most important thing: pick a style and be consistent.

cheers,

dret.