Re: Link relation types for non-GET links

[Klaus Hartke <[e-mail]>]

Erik Wilde wrote:
>> Would it make sense to
>> register a bunch of generic non-GET link relation types, like
>> "create", "execute", "update", "delete"?
>
> 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