Link relation types for non-GET links

[Klaus Hartke <[e-mail]>]

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