Subject: Re: NEW RELATION: action

From: Darrel Miller <[email-masked]>
Date: Thu, 31 Jan 2013 19:31:04 -0500

Hey Jan,

I thought of you as soon as I saw this.  I know we have traveled this road
before and you are not a fan, but let me give you a few examples that I can
think of and you let me know what "harm" they might cause.

It can be used for changing a resource to a new state.

> GET /light/bedroom
< 200 OK
< Link : <http://example.org/light/bedroom/on>; rel="action"; title="On"
<Content-Type: text/plain
Off

This could absolutely be done with PUT, however the client needs to be much
smarter in order to know how to formulate the appropriate body to submit a
PUT request to do exactly the same thing.

It can be used as a way of selecting from a set of options

> GET /survey/12321323/favouritefruit
>
< 200 OK
< Content-Type: application/hal+xml

<resource href="http://example.org/survey/12321323/favouritefruit">
          <link rel="action" title="Orange"
 href="/survey/12321323/favouritefruit?answer=Orange" />
          <link rel="action" title="Apple"
 href="/survey/12321323/favouritefruit?answer=Apple" />
          <link rel="action" title="Banana"
 href="/survey/12321323/favouritefruit?answer=Banana" />
</resource>

Yes there are other ways of doing this, but I can't see any negative
impacts on the system by using this approach.

It can be used for triggering a part of a workflow process

> GET /employee/344/timesheet/20130131
>
< 200 OK
< Content-Type: application/hal+xml

<resource href="http://example.org/employee/344/timesheet/20130131">
          <link rel="action" title="Submit"
 href="/timesheetProcessor?timesheetid=21332434" />
</resource>

I realize this last example steps into "it's not a self-descriptive
request" territory, but let's not get sidetracked into that debate.

The huge benefit in my mind of this link relation is that it opens the door
for generic clients to be able to start doing some simple write operations.
 So far, most of the generic clients that people have been playing around
with have been purely read-only.  This link relation allows a generic
client to display some buttons to a human and allow the human to "poke a
stick" at the resource and actually have an impact.

As I mentioned on twitter to Isoeb, I do think this link relation has the
potential to be abused, however, I do believe it has sufficient value to
mitigate those risks.

Darrel

On Thu, Jan 31, 2013 at 6:11 PM, Jan Algermissen <[email-masked]
> wrote:

> Hi Ioseb,
>
> can you explain your use case?
>
> To me this smells a lot like a (REST-) anti pattern.
>
> For example, instead of invoking an action resource like
>
> GET /content/article/22/publish
>
> you'd rather set it's state:
>
> PUT /content/article/22/publish
>
> <entry>
> ...
> <foo:status>published</foo:status>
> ...
> </entry>
>
> No need for link and 'action' link rel, because you know the resource to
> change anyhow.
>
>
> Maybe I am missing your point though.
>
> Jan
>
>
>
> On 31.01.2013, at 20:10, Ioseb Dzmanashvili <[email-masked]>
> wrote:
>
> > Dear All,
> >
> > I've submitted new draft of the 'create' link relation type:
> http://tools.ietf.org/html/draft-ioseb-dzmanashvili-action-link-relation-00
> >
> > Description:
> > - The link relation is intentionally generic, and it can be used with
>  multiple media types in a wide variety of use cases.
> > - When included in a resource which represents a collection, the 'form'
>  link relation identifies a target resource that represents the form for
> adding a new member to the context collection.
> > - The target IRI points to a resource that is responsible to perform an
> action that may affect state of the context resource or
> >  initiate process.
> >
> > Could you please review?
> > Thanks in advance!
> >
> > Best regards,
> > ioseb
> > --
> > Ioseb Dzmanashvili
> > AzRy LLC
> > Software Architect
> > #8, Chachava str.
> > Tbilisi, 0159, Georgia
> > Mobile: +(995) 99753388
> > github.com/ioseb
> > pecl.php.net/user/ioseb
> > twitter.com/iosebi
> > _______________________________________________
> > link-relations mailing list
> > [email-masked]
> > https://www.ietf.org/mailman/listinfo/link-relations
>
> _______________________________________________
> link-relations mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/link-relations
>

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Fri, 1 Feb 2013 13:44:33 +0400

Hi Jan, 

Thanks for feedback! 

Example one(publishing content):

> GET /posts/1
> Host: domain.org

< HTTP/1.1 200 OK
< Content-Type: application/something
< Content-Length: ...
< Link: </posts/1/publisher urn:publish>; rel="action"; title="Publish"

[BODY HERE]

> POST /posts/1/publisher HTTP/1.1
> Host: domain.org

< HTTP/1.1 303 See Other
< Location: http://domain.org/posts/1

Example two(restarting service):

> GET /service HTTP/1.1
> Host: domain.org

< HTTP/1.1 200 OK
< Content-Type: ...
< Content-Length: ...
< Link: </service/manager>; rel="action urn:restart"; title="Restart"

[BODY HERE]

> POST /service/manager HTTP/1.1
> Host: domain.org

< HTTP/1.1 202 Accepted
< Retry-After: 10
< Link: </service/status>; rel="monitor"

I hope these examples clearly demonstrate purpose of the "action" link relation. 

> To me this smells a lot like a (REST-) anti pattern.

I do not agree. Which REST constraint is violated in this case? Using POST without body is valid and "action" links expose availability of actions which may be performed: 

* without knowing media type;
* without need to construct whole message(to conform PUT's replace semantics);
* no need to use PATCH 
* "action" links can be filtered by client and displayed to user(and here we do not even need additional link relation extensions)

In addition let me show another example: 

> GET /posts HTTP/1.1
> Host: domain.org

> HTTP/1.1 200 OK
> Content-Type: application/vnd.something+json
> Content-Length: ...

{"document": {
"href": "/posts"
"links": {
"item": [{
"href": "/posts/1",
"title": "Post One Title",
"links": {
"action": { "href": "/posts/1/publisher", "title": "Publish" },
"replies": { "href": "/posts/1/replies", "title": "Comments" },
"edit": { "href": "/posts/1", "title": "Edit post" }
}
}, {
"href": "/posts/2",
"title": "Post Two Title",
"links": {
"action": { "href": "/posts/2/publisher", "title": "Publish" },
"replies": { "href": "/posts/2/replies", "title": "Comments" },
"edit": { "href": "/posts/2", "title": "Edit post" }
}
}]
}
}}

Here we have document with hierarchical links(no specific format, just format i frequently use for my implementations). Now if i want to present these links visually i've all information which may be perfectly rendered on mobile devices, for example lets say simple list. Post title is enough for application user. The "action" link relation has enough semantics for application to render it as a "Publish" button alongside the title and if user decides to "publish" the post there is no need for application to: a) go to the server and retrieve full representation in whatever media type; b) modify only one attribute of the retrieved representatin; and c) send modified representation to the server with PUT method. Instead simple POST request can be sent to the resource which knows what to do with the post's state. 

I hope these examples and explanations will help. Thanks again for feedback!

@Darrel
Thank you very much for positive feedback!

Best regards,
ioseb

On Friday, February 1, 2013 at 4:31 AM, Darrel Miller wrote:

> Hey Jan,
> 
> I thought of you as soon as I saw this.  I know we have traveled this road before and you are not a fan, but let me give you a few examples that I can think of and you let me know what "harm" they might cause.   
> 
> This could absolutely be done with PUT, however the client needs to be much smarter in order to know how to formulate the appropriate body to submit a PUT request to do exactly the same thing.   
> 
>           <link rel="action" title="Orange"  href="/survey/12321323/favouritefruit?answer=Orange" /> 
>           <link rel="action" title="Apple"  href="/survey/12321323/favouritefruit?answer=Apple" />  
>           <link rel="action" title="Banana"  href="/survey/12321323/favouritefruit?answer=Banana" /> 
> 
> </resource>
> 
> Yes there are other ways of doing this, but I can't see any negative impacts on the system by using this approach.
> 
> 
>           <link rel="action" title="Submit"  href="/timesheetProcessor?timesheetid=21332434" /> 
> </resource>
> 
> 
> I realize this last example steps into "it's not a self-descriptive request" territory, but let's not get sidetracked into that debate.
> 
> The huge benefit in my mind of this link relation is that it opens the door for generic clients to be able to start doing some simple write operations.  So far, most of the generic clients that people have been playing around with have been purely read-only.  This link relation allows a generic client to display some buttons to a human and allow the human to "poke a stick" at the resource and actually have an impact. 
> 
> As I mentioned on twitter to Isoeb, I do think this link relation has the potential to be abused, however, I do believe it has sufficient value to mitigate those risks.
> 
> Darrel
> 
> 
> On Thu, Jan 31, 2013 at 6:11 PM, Jan Algermissen <[email-masked] (mailto:[email-masked])> wrote:
> > Hi Ioseb,
> > 
> > No need for link and 'action' link rel, because you know the resource to change anyhow.
> > 
> > 
> > On 31.01.2013, at 20:10, Ioseb Dzmanashvili <[email-masked] (mailto:[email-masked])> wrote:
> > 
> > > Dear All,
> > >
> > > I've submitted new draft of the 'create' link relation type: http://tools.ietf.org/html/draft-ioseb-dzmanashvili-action-link-relation-00
> > >
> > > Description:
> > > - The link relation is intentionally generic, and it can be used with  multiple media types in a wide variety of use cases.
> > > - When included in a resource which represents a collection, the 'form'  link relation identifies a target resource that represents the form for adding a new member to the context collection.
> > > - The target IRI points to a resource that is responsible to perform an action that may affect state of the context resource or
> > >  initiate process.
> > >
> > > Could you please review?
> > > Thanks in advance!
> > >
> > > Best regards,
> > > ioseb
> > > --
> > > Ioseb Dzmanashvili
> > > AzRy LLC
> > > Software Architect
> > > #8, Chachava str.
> > > Tbilisi, 0159, Georgia
> > > Mobile: +(995) 99753388
> > > github.com/ioseb (http://github.com/ioseb)
> > > pecl.php.net/user/ioseb (http://pecl.php.net/user/ioseb)
> > > twitter.com/iosebi (http://twitter.com/iosebi)
> > > [email-masked] (mailto:[email-masked])
> > [email-masked] (mailto:[email-masked])

---

From: "Markus Lanthaler" <[email-masked]>
Date: Fri, 1 Feb 2013 12:31:27 +0100

On Friday, February 01, 2013 10:45 AM, Ioseb Dzmanashvili wrote:

> I do not agree. Which REST constraint is violated in this case?
> Using POST without body is valid and "action" links expose
> availability of actions which may be performed: 
>
> * "action" links can be filtered by client and displayed to
> user(and here we do not even need additional link relation
> extensions)

The problem is they can just be filtered by clients who know about them. How would a generic crawler know it has to avoid those action links? For example, looking at your example:

< HTTP/1.1 200 OK
< Content-Type: ...
< Content-Length: ...

Imagine that the link would be embedded in a HTML page:

<a href="/service/manager" rel="action urn:restart">Restart</a>

What would happen if a crawler follows that link? Would the service be restarted? Assuming that you say links with this relation type just accept POST (and I think that's what Jan was concerned about because it wasn't clear in your initial mail), would it result in an error because it uses GET?

On Friday, February 1, 2013 at 4:31 AM, Darrel Miller wrote:

> Yes there are other ways of doing this, but I can't see any
> negative impacts on the system by using this approach.
>
> [..]
>
> The huge benefit in my mind of this link relation is that it
> opens the door for generic clients to be able to start doing
> some simple write operations.   

Talking about HTML, how is that different from using an empty form (just submit button) and @method=POST?

--
Markus Lanthaler
@markuslanthaler

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Fri, 1 Feb 2013 15:42:51 +0400

Hi Markus, 

Draft doesn't mention anything about GET request to "action" links for the moment, though i think service implementors can use: 3xx status codes to redirect user agent somewhere else, return 4xx(405 Method Not Allowed for example) etc.... But the action must be performed only if client sends POST request.

P.S.
i truly believe that such links must not be exposed to public unless client doesn't have enough permissions. 

Cheers,
ioseb

---

From: Darrel Miller <[email-masked]>
Date: Fri, 1 Feb 2013 08:30:26 -0500

Ioseb,

On Fri, Feb 1, 2013 at 6:42 AM, Ioseb Dzmanashvili <
[email-masked]> wrote:

> Draft doesn't mention anything about GET request to "action" links for the
> moment, though i think service implementors can use: 3xx status codes to
> redirect user agent somewhere else, return 4xx(405 Method Not Allowed for
> example) etc.... But the action must be performed only if client sends POST
> request.
>
>
I would be tempted to just use the GET as a placeholder for documentation
on what the POST does.

Darrel

---

From: "Markus Lanthaler" <[email-masked]>
Date: Fri, 1 Feb 2013 14:52:36 +0100

On Friday, February 01, 2013 2:26 PM, Darrel Miller wrote:

> It isn't different.  It allows that same functionality to be embedded in
any
> hypermedia type, Or even just in link headers.  I think the fact that you
> can do it in HTML further validates this proposal.

Hmm.. the reason I do not particularly like it is because it basically means
nothing. It's basically that same as "accepts-post", and POST has no
semantics at all. It "works" in HTML because there's a human reading and
interpreting the text. If you would be going to use that in
machine-to-machine communication you would either need to infer the meaning
from the target URL (which you shouldn't because they are opaque) or use
something else (a title, a second rel, etc.) to convey the meaning. AFAICS,
you cannot do anything useful with just rel="action".

P.S.: Darrel, you replied just to me

--
Markus Lanthaler
@markuslanthaler

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Fri, 1 Feb 2013 18:53:52 +0400

Hi Mike, 

Thanks for feedback!

> 1) "action" will always be unsafe, but MAY be either idempotent (PUT/DELETE) or non-idempotent (PATCH/POST). This is a problem. Either a) establish it as one or the other or, b) create two relations to handle each case.

Regarding idempotency i do not have clear use cases right now(some examples would be great here), hence no idea what second link relation type should be. Establishing the "action" as unsafe looks more appropriate for me at the moment. 

> 2) since "action" will always be unsafe, it MUST NOT be applied to elements already defined as "safe" by the media type (HTML.A, HTML.LINK, HTML.IFRAME, HTML.IMG, HTML.FORM@method="get", etc.). Wording should be added that makes this clear.

Accepted!

Cheers,
ioseb

On Friday, February 1, 2013 at 5:36 PM, mca wrote:

> My initial comments are:
> 
> 1) "action" will always be unsafe, but MAY be either idempotent (PUT/DELETE) or non-idempotent (PATCH/POST). This is a problem. Either a) establish it as one or the other or, b) create two relations to handle each case. 
> 
> 2) since "action" will always be unsafe, it MUST NOT be applied to elements already defined as "safe" by the media type (HTML.A, HTML.LINK, HTML.IFRAME, HTML.IMG, HTML.FORM@method="get", etc.). Wording should be added that makes this clear. 
> 
> 
> 
> mca
> +1.859.757.1449
> skype: mca.amundsen
> http://amundsen.com/blog/
> http://twitter.com/mamund
> https://github.com/mamund
> http://www.linkedin.com/in/mikeamundsen
> 
> 
> 
> On Thu, Jan 31, 2013 at 2:10 PM, Ioseb Dzmanashvili <[email-masked] (mailto:[email-masked])> wrote:
> > Dear All,
> >

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Fri, 1 Feb 2013 19:16:26 +0400

I'm guessing something went wrong with email thread. I see some messages in mail list which missed my mailbox and do not see @mamund's email message at all. I'm including combined conversation in this email:

> Ioseb Dzmanashvili wrote:
> 
> Hi Mike, 
> 
> Thanks for feedback!
> 
> > Mike Amundsen wrote:
> > > > > On Fri, Feb 1, 2013 at 6:42 AM, Ioseb Dzmanashvili <ioseb.dzmanashvili at gmail.com (http://gmail.com)> wrote:
> > > > I would be tempted to just use the GET as a placeholder for documentation on what the POST does.
> > > > 
> > > > Darrel
> > > > > Markus,
> > > > > 
> > > > > 
> > > > > On Fri, Feb 1, 2013 at 6:31 AM, Markus Lanthaler <markus.lanthaler at gmx.net (http://gmx.net)> wrote:
> > > > > 
> > > > > It isn't different.  It allows that same functionality to be embedded in any hypermedia type, Or even just in link headers.  I think the fact that you can do it in HTML further validates this proposal.
> > > > > 
> > > > > Darrel
> > > > 
> > > 
> > > 
> > > 
> > 
> > 
> 
> 
> > > 
> > 
> > 
> > 
> 
> 
> > 
> 
> 
> 
> 

cheers,
ioseb

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Fri, 1 Feb 2013 19:46:39 +0400

Dear all,

>From previous messages questions raised regarding GET request, below are comments from @Mike and @Darrel.

> I would be tempted to just use the GET as a placeholder for documentation on what the POST does. 

----------------------------------------

@Markus
> nothing. It's basically that same as "accepts-post", and POST has no semantics at all. 

Draft defines semantics and its very different. It implies that accepting resource can affect state of the context resource or initiate some process in contrast to POST which may mean anything. Additionally it creates possibility to attach multiple "action" links to a particular resource that may or be rendered for users(or used in M2M communication if additional semantics are defined) and consuming agent doesn't need to assume or guess anything. 

> It "works" in HTML because there's a human reading and interpreting the text.

Not only in HTML. This will work in any application which involves human interaction. 

> If you would be going to use that in machine-to-machine communication you would either need to infer the meaning
> something else (a title, a second rel, etc.) to convey the meaning.

There is no need to to infer something from the target URI or use something else. Draft states that: "Actual function to be performed by the server, MAY be advertised by including an extension link relation types as defined per Section 4.2 of [RFC5988]." which is perfectly valid approach especially when there is need for M2M interaction. I do not get what is wrong with second rel? There are bunch of link relations which doesn't add any value to M2M interaction unless participant(s) are trained correspondingly.

> AFAICS, you cannot do anything useful with just rel="action".

I do not agree. a) The relation works perfectly in applications where user interaction exists and there is no need for defining additional semantics; and b) as i noted above spec clearly says how to extend it's meaning.

Best regards,
ioseb

On Friday, February 1, 2013 at 7:16 PM, Ioseb Dzmanashvili wrote:

> > > > Markus

---

From: "Markus Lanthaler" <[email-masked]>
Date: Fri, 1 Feb 2013 17:10:58 +0100

On Friday, February 01, 2013 4:47 PM , Ioseb Dzmanashvili wrote:

> There is no need to to infer something from the target URI or use something else.
> Draft states that: "Actual function to be performed by the server, MAY be
> advertised by including an extension link relation types as defined per Section 4.2
> of [RFC5988]."

MAY means that it's not required. If it's not required, what does such a link mean if there isn't any other information?

> I do not get what is wrong with second rel? There are bunch of link relations
> which doesn't add any value to M2M interaction unless participant(s) are
> trained correspondingly.

There's nothing wrong with a second rel. It's also true that consumers need to recognize the token to do something useful. The problem is that the "action" rel just says, you can POST to this URL, if you do so, you SHOULD not include a body in your POST.

> I do not agree. a) The relation works perfectly in applications
> where user interaction exists and there is no need for defining
> additional semantics;
> and b) as i noted above spec clearly says how to extend it's
> meaning.

So, in a user facing app, what does this mean: <a href="http://example.com/dlfkj" rel="action">OK</a>?

What I'm trying to say is, that basically all the information is in the "OK" (well, in this case it isn't) and not in "action". Maybe it's also just that action is irritating me. I definitely find it too generic and overloaded. Perhaps something like "ping" (which itself is also quite overloaded) might work better. Just an idea.

--
Markus Lanthaler
@markuslanthaler

---

From: mca <[email-masked]>
Date: Fri, 1 Feb 2013 08:36:30 -0500

My initial comments are:

1) "action" will always be unsafe, but MAY be either idempotent
(PUT/DELETE) or non-idempotent (PATCH/POST). This is a problem. Either a)
establish it as one or the other or, b) create two relations to handle each
case.

2) since "action" will always be unsafe, it MUST NOT be applied to elements
already defined as "safe" by the media type (HTML.A, HTML.LINK,
HTML.IFRAME, HTML.IMG, HTML.FORM@method="get", etc.). Wording should be
added that makes this clear.

mca
+1.859.757.1449
skype: mca.amundsen

---

From: "Darrel Miller" <[email-masked]>
Date: Fri, 1 Feb 2013 09:08:39 -0500

Markus,

> -----Original Message-----
> From: Markus Lanthaler [mailto:[email-masked]]
> 
semantics
> at all. It "works" in HTML because there's a human reading and
interpreting
> the text. If you would be going to use that in machine-to-machine
> communication you would either need to infer the meaning from the target
> URL (which you shouldn't because they are opaque) or use something else (a
> title, a second rel, etc.) to convey the meaning. AFAICS, you cannot do
> anything useful with just rel="action".
> 

I completely agree that "action" means nothing to client code other than
"this is some unsafe operation to be performed on a resource".  I also agree
that is has very little value to m2m clients.  

However, 99% of the software I have written over the past 18 years has been
operated by a human.  So, I'm much more concerned about the human driven
scenario.  Over the past few years my tendency has been to write client
software that focuses on presenting information to humans and then capturing
their intent.  I rarely need my user-agent to actually understand the
consequences of the user's action.  It's only job is to faithfully relay the
user's intent to the resource.

I recognize that this rel is not going to be valuable to everyone. That's
fine with me.

> P.S.: Darrel, you replied just to me
Yeah, I always make that mistake when replying in the Gmail interface.  I
forwarded the message to the list after I realized my mistake.

Darrel

---

From: mca <[email-masked]>
Date: Fri, 1 Feb 2013 11:18:15 -0500

Regarding idempotency i do not have clear use cases right now(some examples
would be great here), hence no idea what second link relation type should
be. Establishing the "action" as unsafe looks more appropriate for me at
the moment.

Consider a case where a sent an unsafe request to a server and get NO
answer back. I don't know what happened. Should I re-try? if this is an
idempotent action (PUT/DELETE) I know I can retry w/o unwanted
side-effects. Server might say "that record is already modified , or "OK,
done", etc. and I'd be satisfied.  But if the action was
non-idempotent (PATCH/POST), then I proly won't re-try since it might
result in multiple entries, etc.

@rel="action" doesn't tell me whether the unsafe action I am about to
commit is idempotent or non-idempotent.  This is a problem. It means I must
rely  on human-readable docs for the answer and that means this is unlikely
to work for "bot" or automated client cases.

mca
+1.859.757.1449
skype: mca.amundsen

On Fri, Feb 1, 2013 at 10:16 AM, Ioseb Dzmanashvili <
[email-masked]> wrote:

> I'm guessing something went wrong with email thread. I see some messages
> in mail list which missed my mailbox and do not see @mamund's email message
> at all. I'm including combined conversation in this email:
>
> Regarding idempotency i do not have clear use cases right now(some
> examples would be great here), hence no idea what second link relation type
> should be. Establishing the "action" as unsafe looks more appropriate for
> me at the moment.
>
> > 2) since "action" will always be unsafe, it MUST NOT be applied to
> elements already defined as "safe" by the media type (HTML.A, HTML.LINK,
> 2) since "action" will always be unsafe, it MUST NOT be applied to
> elements already defined as "safe" by the media type (HTML.A, HTML.LINK,
> On Fri, Feb 1, 2013 at 6:42 AM, Ioseb Dzmanashvili <ioseb.dzmanashvili at
> gmail.com> wrote:
> On Fri, Feb 1, 2013 at 6:31 AM, Markus Lanthaler <markus.lanthaler at
> gmx.net> wrote:
>
> any hypermedia type, Or even just in link headers.  I think the fact that
> you can do it in HTML further validates this proposal.
>
> Darrel
>
>
> cheers,
> ioseb
>
> The problem is they can just be filtered by clients who know about them.
> How would a generic crawler know it has to avoid those action links? For
> example, looking at your example:
>
>
> < HTTP/1.1 200 OK
> < Content-Type: ...
> < Content-Length: ...
> What would happen if a crawler follows that link? Would the service be
> restarted? Assuming that you say links with this relation type just accept
> POST (and I think that's what Jan was concerned about because it wasn't
> clear in your initial mail), would it result in an error because it uses
> GET?
>
>

---

From: Jan Algermissen <[email-masked]>
Date: Fri, 1 Feb 2013 17:31:02 +0100

> This could absolutely be done with PUT, however the client needs to be much smarter in order to know how to formulate the appropriate body to submit a PUT request to do exactly the same thing. 

But now client would ever PUT/POST to such a link, without understanding it. Or? Given it requires understanding, the need for a generic mechanism is gone. Just use a specific link rel instead. Much cleaner, IMHO.

For the sake of displaying a button: this can always be done if there is a title in the link.

> Yes there are other ways of doing this, but I can't see any negative impacts on the system by using this approach.

In general: what is the need for a generic mechanism, if no client would interact with the target unless it understands the rel anyhow?

I'd say it's pretty much YAGNI.

> I realize this last example steps into "it's not a self-descriptive request" territory, but let's not get sidetracked into that debate.

Yes - but it is another aspect I'd 'object' to.

> 
> The huge benefit in my mind of this link relation is that it opens the door for generic clients to be able to start doing some simple write operations.

This is what I do not see happening - you?

Jan

>  So far, most of the generic clients that people have been playing around with have been purely read-only.  This link relation allows a generic client to display some buttons to a human and allow the human to "poke a stick" at the resource and actually have an impact.
> 
> On Thu, Jan 31, 2013 at 6:11 PM, Jan Algermissen <[email-masked]> wrote:
> Hi Ioseb,
> 
> On 31.01.2013, at 20:10, Ioseb Dzmanashvili <[email-masked]> wrote:
> 
> > Dear All,
> >

---

From: Jan Algermissen <[email-masked]>
Date: Fri, 1 Feb 2013 17:32:20 +0100

On 01.02.2013, at 12:31, "Markus Lanthaler" <[email-masked]> wrote:

> What would happen if a crawler follows that link?

That is another concern, but a GET should be save anyhow - eh?

Jan

> Would the service be restarted? Assuming that you say links with this relation type just accept POST (and I think that's what Jan was concerned about because it wasn't clear in your initial mail), would it result in an error because it uses GET?
> 
>

---

From: Jan Algermissen <[email-masked]>
Date: Fri, 1 Feb 2013 17:39:01 +0100

> user's intent to the resource.

So then ... if your UA sees

Link: </foo>; rel="pub";title="Publish" 

just display a [Publish] Button.

(Set aside the fact that I deeply dislike action-URIs and would wholeheartedly 'fight' anything that can possibly lead people to think it is a REST best practice of some sort)

Avoiding them yields better systems, IMHO.

Jan

---

From: Darrel Miller <[email-masked]>
Date: Fri, 1 Feb 2013 12:00:30 -0500

Jan,

On Fri, Feb 1, 2013 at 11:39 AM, Jan Algermissen <[email-masked]

> just display a [Publish] Button.
First, "pub" is not a valid registered link relation, nor is it valid
syntax for an extended link relation.  Second, what additional semantics is
"pub" providing a user-agent that "action" does not already provide.  Why
does a user-agent need to know that this link is "publishing"?

Arguing that "action" is too generic and therefore useless, is like arguing
that an <a/> link in HTML is useless because it doesn't tell you what kind
of document is being pointed at.  We should strive to NOT include semantics
that the UA does not need to complete its task.  Providing unused semantics
just creates useless coupling.

Darrel

---

From: Jan Algermissen <[email-masked]>
Date: Fri, 1 Feb 2013 19:11:47 +0100

On 01.02.2013, at 18:00, Darrel Miller <[email-masked]> wrote:

> 
> Jan,
> 
> On Fri, Feb 1, 2013 at 11:39 AM, Jan Algermissen <[email-masked]> wrote:
> 
> 
> First, "pub" is not a valid registered link relation, nor is it valid syntax for an extended link relation.  

Well, consider it an example :-)

> Second, what additional semantics is "pub" providing a user-agent that "action" does not already provide.  Why does a user-agent need to know that this link is "publishing"?

If it does not understand the semantic, why would it POST/PUT to the target?

> 
> Arguing that "action" is too generic and therefore useless, is like arguing that an <a/> link in HTML is useless because it doesn't tell you what kind of document is being pointed at.  

<a> makes sense, because I can allways GET it.

'action' is trying to do the same for POST/PUT ... but no client will ever traverse that link with a POST/PUT unless it understands the refinement of the rel (e.g. urn:publish as mentioned)

Jan

> We should strive to NOT include semantics that the UA does not need to complete its task.  Providing unused semantics just creates useless coupling.
> 
> Darrel

---

From: Darrel Miller <[email-masked]>
Date: Fri, 1 Feb 2013 13:58:51 -0500

Jan,

On Fri, Feb 1, 2013 at 1:11 PM, Jan Algermissen
<[email-masked]>wrote:

> rel="action" makes sense because you can always POST an empty body to it.

> 'action' is trying to do the same for POST/PUT ... but no client will ever
> traverse that link with a POST/PUT unless it understands the refinement of
> the rel (e.g. urn:publish as mentioned)
>
>
I don't understand why you think this.  A user-agent will POST to the link
if the human driving the user-agent decides they want to do that.  The only
job of the UA is to provide an affordance that allows the human to make
that choice.  A user-agent does not have any need to understand what
"publish" means any more than a user-agent knows what is happening when
they follow a rel="search" link.  As long as the UA has sufficient
information to be able to activate the link when requested, that is enough.

Darrel

---

From: Jan Algermissen <[email-masked]>
Date: Fri, 1 Feb 2013 20:18:31 +0100

On 01.02.2013, at 19:58, Darrel Miller <[email-masked]> wrote:

> Jan,
> 
> 
> On Fri, Feb 1, 2013 at 1:11 PM, Jan Algermissen <[email-masked]> wrote:
> 
> I don't understand why you think this.  A user-agent will POST to the link if the human driving the user-agent decides they want to do that.

I meant automatically.

>  The only job of the UA is to provide an affordance that allows the human to make that choice.  A user-agent does not have any need to understand what "publish" means any more than a user-agent knows what is happening when they follow a rel="search" link.  As long as the UA has sufficient information to be able to activate the link when requested, that is enough.

Yes - and for that you do not need 'action'.

Jan

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Fri, 1 Feb 2013 23:40:40 +0400

Markus,

> MAY means that it's not required. If it's not required, what does such a link mean if there isn't any other information?

Yes, "MAY" mean that it's not required but states that it's possible and there is a way to add additional meaning to the link without redefining "action" semantics each time like: "hey, here i have my custom link relation urn:boa:boa:publish" and just send POST request to me without body if you want to publish this piece of content". This is one of the purposes of the "action" relation type. 

> There's nothing wrong with a second rel. It's also true that consumers need to recognize the token to do something useful. The problem is that the "action" rel just says, you can POST to this URL,…

Yes "action" says exactly this and it is absolutely enough for application code: to recognise actions in the representation; render these actions as buttons(or whatever else); and if user chooses one of them just send POST requests to the URI without making any assumptions.

> So, in a user facing app, what does this mean: <a href="http://example.com/dlfkj" rel="action">OK</a>?

As of current state of the draft nothing special. As i already mentioned in previous emails behaviour for "GET" request is not defined(and i think discussions are for such purposes to make specs clear). But:

* we have forms in HTML and instead of using "action" links it's possible to embed form + multiple action buttons which after rendering will make clear for users what to do next.
* I'd ask what what does this link means: <a href="/resource" rel="stylesheet">Stylesheet</a>? here is how it solved in HTML spec [1] there is restriction: "The stylesheet (http://www.w3.org/TR/html5/links.html#link-type-stylesheet) keyword may be used with link (http://www.w3.org/TR/html5/document-metadata.html#the-link-element) elements. This keyword creates an external resource link (http://www.w3.org/TR/html5/links.html#external-resource-link) that contributes to the styling processing model (http://www.w3.org/TR/html5/document-metadata.html#styling)."
* There are other media formats can benefit from "action" link relation and HTML is not absolute must.
* It makes perfect sense when used in a Link header.

> What I'm trying to say is, that basically all the information is in the "OK" (well, in this case it isn't) and not in "action". Maybe it's also just that action is irritating me. I definitely find…

I do not get how "ping" is related.

[1] http://www.w3.org/TR/html5/links.html#link-type-stylesheet

Cheers,
ioseb

---

From: Jan Algermissen <[email-masked]>
Date: Fri, 1 Feb 2013 21:23:59 +0100

> Yes - and for that you do not need 'action'.

In addition: since you cannot specifiy the kind of payload to send, 'action' really only manifests the (anti-)pattern of action resources.

What you really want is something like an inline form to specify the payload. And this is where it gets interesting, because Ioseb has recently registered the (very valuable) edit-form and ceate-form relations.

So, why not use that one and render a button for it. Upon clicking the button, the client can download the form, display an overlay to enter the data and present a 'send' button.?

The link title will make for a fine button label.

Link: </foo>; rel="edit-form"; title="Update customer data"

Link: </workflows>; rel="create-form"; title="Initiate new workflow"

Jan

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Sat, 2 Feb 2013 00:27:04 +0400

Jan, 

> For the sake of displaying a button: this can always be done if there is a title in the link.

The argument doesn't stand. For example:

Link: </some/resource>; title="Do Something" 

doesn't imply that it must be rendered as a button nor behave like action which is required to send POST request to the server. It's just a link nothing more. Agents may only assume that they can fetch it. But:

Link: </some/resource>; rel="action" title="Do Something" 

already has enough semantics(i mean if "action" link is already defined and known for agents) and it clearly mean that it can be rendered as an action button which MUST(or SHOULD) send POST request to the server.

> 'action' is trying to do the same for POST/PUT ... but no client will ever traverse that link with a POST/PUT unless it understands the refinement of the rel (e.g. urn:publish as mentioned)

This passage makes me think that whole world of URIs/HTTP works without interventions and everything is traversed by some mysterious automated agents :-) if agents are automated, they must be taught to recognise registered link relations types at least. I do not think that any automated agent "traverses" HTML forms(or other forms) unless they are taught to do so(i assume someone provides agent with input and agent recognises something and does something etc...)

>> The only job of the UA is to provide an affordance that allows the human to make that choice.  A user-agent does not have 
>> any need to understand what "publish" means any more than a user-agent knows what is happening when they follow a 
>> rel="search" link.  As long as the UA has sufficient information to be able to activate the link when requested, that is enough.

> Host: domain.org

< HTTP/1.1 200 OK
< Content-Type: ...
< Content-Length: ...
< Link: </service/restarter>; rel="action"; title="Restart",
<       </service/suspender>; rel="action"; title="Suspend"
< 
< [BODY HERE]

This message is enough for program to: a) render information on the screen; b) determine actions with implied semantics: "just POST to this URI" and expose these actions to user. Now my questions are:

1) What is wrong with this approach (other than automated agents couldn't traverse these links)?
2) How could links without rel="action" help me?
3) How it would be better if i defined two separate custom relations: "urn:restart" and "urn:suspend".
4) What is violated(REST, Web Linking rfc? HTTP protocol?)

P.S.
I understand M2M concerns, though i do not get the fact that M2M is considered superior over "user->app->service" interaction and especially that all APIs(call it RESTful, Hypermedia or WebAPI) in the world must be blindly traversable from start to end.

P.P.S.
Could you please CC me in your and Darrel's discussion? I'm not receiving these messages unfortunately. 

Cheers,
Ioseb

On Friday, February 1, 2013 at 8:32 PM, Jan Algermissen wrote:

> 
> On 01.02.2013, at 12:31, "Markus Lanthaler" <[email-masked] (mailto:[email-masked])> wrote:
>

---

From: Jan Algermissen <[email-masked]>
Date: Fri, 1 Feb 2013 21:41:51 +0100

On 01.02.2013, at 21:27, Ioseb Dzmanashvili <[email-masked]> wrote:

> These actions are for application users(people).

If the end user is human ... why not use HTML?

Jan

---

From: Darrel Miller <[email-masked]>
Date: Fri, 1 Feb 2013 15:43:08 -0500

Jan,

On Fri, Feb 1, 2013 at 3:23 PM, Jan Algermissen
<[email-masked]>wrote:

> >> The only job of the UA is to provide an affordance that allows the
> human to make that choice.  A user-agent does not have any need to
> understand what "publish" means any more than a user-agent knows what is
> happening when they follow a rel="search" link.  As long as the UA has
> sufficient information to be able to activate the link when requested, that
> is enough.
> >
Without "action" a user-agent does not know that it should POST with an
empty body.

> In addition: since you cannot specifiy the kind of payload to send,
> 'action' really only manifests the (anti-)pattern of action resources.
>
> What you really want is something like an inline form to specify the
> payload. And this is where it gets interesting, because Ioseb has recently
> registered the (very valuable) edit-form and ceate-form relations.
>
>
So, does this example meet your constraints?

> POST /myservice
> Content-type: application/x-www-urlencoded-form
> action=restart

I don't see how this is more self-descriptive.  Just because I created a
payload, why is that now magically kosher.

create-form and edit-form are great, but what about when I'm not creating
or editing resources?

> So, why not use that one and render a button for it. Upon clicking the
> button, the client can download the form, display an overlay to enter the
> data and present a 'send' button.?
>
>
Because there is no data to send.  The entire UI interaction is _pressing_
the button.

Let me provide a visual example

http://demo.presscoders.com/designfolio/files/2012/04/launchButton-logo-big.jpg

:-)

Darrel

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Sat, 2 Feb 2013 00:43:42 +0400

Jan,

> If the end user is human ... why not use HTML?

In this particular case it's an Obj-C App. It's not an HTML app.

ioseb 

On Saturday, February 2, 2013 at 12:41 AM, Jan Algermissen wrote:

> 
> On 01.02.2013, at 21:27, Ioseb Dzmanashvili <[email-masked] (mailto:[email-masked])> wrote:
>

---

From: Darrel Miller <[email-masked]>
Date: Fri, 1 Feb 2013 15:46:22 -0500

Because HTML is designed to represent the semantic content of a textual
document.  The fact that it has been abused to be used for everything under
the sun does not mean that there are not better media types out there for
other scenarios.  For example, for rendering UIs for sets of structured
data, HTML is severely lacking.

Darrel

---

From: Jan Algermissen <[email-masked]>
Date: Fri, 1 Feb 2013 22:34:57 +0100

On 01.02.2013, at 21:43, Darrel Miller <[email-masked]> wrote:

> I don't see how this is more self-descriptive.  

It is not. The media type is too generic.

I'd redesign the whole thing to (maybe) yield more overall value in terms of re-use etc.

When you restart something, you create something (a process of some sort). I'd be interested in that process (e.g. to monitor it, share it's link etc.)

I'd also like to have an extensible format (maybe several incompatible variants in the future, to conneg on) that I can use to specify information about the job to start.

E.g.

POST /processes
Content-Type: application/foo.process

<process>
  <type>MyService</type>
  <priority>...</priority>
</process>

IOW, the fact that a service is restarted feels like an implementation detail, covering up what you really want to achieve and in addition leaking out, leading to a less stable-over-time API.

That's all gut feeling, but it is the same gut feeling every time I see POST /service?myAction . Not doing this, usually triggers thoughts leading down a path to a better (more coarse grained, reusable, evolvable) API.

> Just because I created a payload, why is that now magically kosher.
> 
> create-form and edit-form are great, but what about when I'm not creating or editing resources?

I'd say that you can almost always understand a POST to create something (e.g. a process). Even if it is just the process of doing whatever the POST triggers on the server. It often has an end state I'd like to be able to review or share or use as a starting point to proceed through the application.

> Because there is no data to send.  The entire UI interaction is _pressing_ the button.

See comments above (and IMHO it smells RPCish and is ... boring ... if the latter counts as an API design principle :-).

Jan

---

From: mike amundsen <[email-masked]>
Date: Fri, 1 Feb 2013 16:41:13 -0500

Is "action" going to be defined as MUST NOT be applied to a form-like
element in the message? IOW, is action only valid when there is no body to
send?

mamund
+1.859.757.1449
skype: mca.amundsen

On Fri, Feb 1, 2013 at 4:34 PM, Jan Algermissen
<[email-masked]>wrote:

> When you restart something, you create something (a process of some sort).
> I'd be interested in that process (e.g. to monitor it, share it's link etc.)
>
> I'd also like to have an extensible format (maybe several incompatible
> variants in the future, to conneg on) that I can use to specify information
> about the job to start.
>
> E.g.
>
> POST /processes
> IOW, the fact that a service is restarted feels like an implementation
> detail, covering up what you really want to achieve and in addition leaking
> out, leading to a less stable-over-time API.
>
> That's all gut feeling, but it is the same gut feeling every time I see
> POST /service?myAction . Not doing this, usually triggers thoughts leading
> down a path to a better (more coarse grained, reusable, evolvable) API.
>
>
>
> I'd say that you can almost always understand a POST to create something
> (e.g. a process). Even if it is just the process of doing whatever the POST
> triggers on the server. It often has an end state I'd like to be able to
> review or share or use as a starting point to proceed through the
> application.
>
> >
> >
> >
> See comments above (and IMHO it smells RPCish and is ... boring ... if the
> latter counts as an API design principle :-).
>
> Jan
>
>
> >

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Sat, 2 Feb 2013 01:48:35 +0400

Mike,

> Is "action" going to be defined as MUST NOT be applied to a form-like element in the message? IOW, is action only valid when there is no body to send?

As of current definition: "In order to perform action, clients SHOULD send an empty POST request to the target resource." More details are in section 3.1. [1]

While writing spec i didn't have such use cases(i.e. applying it to form like elements in the message) and driving use cases were as i already mentioned several times in this thread simple true/false like actions. I'd be happy to hear about more use cases though. 

[1]. http://tools.ietf.org/html/draft-ioseb-dzmanashvili-action-link-relation-00#section-3.1

Cheers,
ioseb

On Saturday, February 2, 2013 at 1:41 AM, mike amundsen wrote:

> Is "action" going to be defined as MUST NOT be applied to a form-like element in the message? IOW, is action only valid when there is no body to send?
> 
> 
> mamund
> +1.859.757.1449
> skype: mca.amundsen
> On Fri, Feb 1, 2013 at 4:34 PM, Jan Algermissen <[email-masked] (mailto:[email-masked])> wrote:
> > 
> > On 01.02.2013, at 21:43, Darrel Miller <[email-masked] (mailto:[email-masked])> wrote:
> > 
> > >

---

From: Darrel Miller <[email-masked]>
Date: Fri, 1 Feb 2013 16:50:52 -0500

Mike,

Speaking for myself only, I would see value to limiting "action" to be only
for POST with no body. If you do not apply this constraint, then how can a
client know what type of body should be posted.

I know Ioseb was suggesting that a second "extended type" rel could be used
to provide additional details however, there is a phrase in RFC 5988...

"Relation types SHOULD NOT infer any additional semantics based upon
   the presence or absence of another link relation type, or its own
   cardinality of occurrence"

Which I interpret as meaning, that "action" and the extended type must
stand alone independently and different clients just interpret one or the
other.  Therefore, for me, there is no way for an "action" link relation to
assist a client in formulating a body.

Darrel

On Fri, Feb 1, 2013 at 4:41 PM, mike amundsen <[email-masked]> wrote:

> On Fri, Feb 1, 2013 at 4:34 PM, Jan Algermissen <
> [email-masked]> wrote:
>
>>
>> When you restart something, you create something (a process of some
>> sort). I'd be interested in that process (e.g. to monitor it, share it's
>> link etc.)
>>
>> See comments above (and IMHO it smells RPCish and is ... boring ... if
>> the latter counts as an API design principle :-).
>>
>> Jan
>>
>>
>> >

---

From: mike amundsen <[email-masked]>
Date: Fri, 1 Feb 2013 16:51:51 -0500

so, "action" is only for sending an empty HTTP.POST request; nothing else.
no other protocol use (XMPP, WS, FTP, etc.) no HTTP.PUT, PATCH, DELETE, or
any other method that might be added to HTTP in the future, correct?

mamund
+1.859.757.1449
skype: mca.amundsen

On Fri, Feb 1, 2013 at 4:48 PM, Ioseb Dzmanashvili <
[email-masked]> wrote:

> As of current definition: "In order to perform action, clients SHOULD send
> an empty POST request to the target resource." More details are in section
> 3.1. [1]
>
> While writing spec i didn't have such use cases(i.e. applying it to form
> like elements in the message) and driving use cases were as i already
> mentioned several times in this thread simple true/false like actions. I'd
> be happy to hear about more use cases though.
>
> [1].
> http://tools.ietf.org/html/draft-ioseb-dzmanashvili-action-link-relation-00#section-3.1
>
> Cheers,
> ioseb
>

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Sat, 2 Feb 2013 01:58:24 +0400

Mike,

> so, "action" is only for sending an empty HTTP.POST request; nothing else. no other protocol use (XMPP, WS, FTP, etc.) no HTTP.PUT, PATCH, DELETE, or any 
> other method that might be added to HTTP in the future, correct?

Exactly, i never thought about this link relation in terms of other method than POST(except GET which is not clarified in the spec yet). Same is true regarding protocols, i never thought about using this relation with XMPP or WS etc... 

@Darrel
> I know Ioseb was suggesting that a second "extended type" rel could be used to provide additional details however, there is a > phrase in RFC 5988...
> 
> "Relation types SHOULD NOT infer any additional semantics based upon the presence or absence of another link relation type, 
> or its own cardinality of occurrence"

That is why i described this possibility with MAY.

ioseb 

On Saturday, February 2, 2013 at 1:51 AM, mike amundsen wrote:

> so, "action" is only for sending an empty HTTP.POST request; nothing else. no other protocol use (XMPP, WS, FTP, etc.) no HTTP.PUT, PATCH, DELETE, or any other method that might be added to HTTP in the future, correct?
> 
> mamund
> +1.859.757.1449
> skype: mca.amundsen
> On Fri, Feb 1, 2013 at 4:48 PM, Ioseb Dzmanashvili <[email-masked] (mailto:[email-masked])> wrote:
> > Mike,
> > 
> > > +1.859.757.1449 (tel:%2B1.859.757.1449)
> > > skype: mca.amundsen

---

From: Darrel Miller <[email-masked]>
Date: Fri, 1 Feb 2013 17:05:33 -0500

Mike,

> any other method that might be added to HTTP in the future, correct?
If another protocol has an equivalent operation which is unsafe and
requires no parameters, then  I see no reason why there cannot be a mapping
for that protocol.  However, for HTTP the only other method I can imagine
that might map is DELETE.  However, that would then require the
specification of a link-extension parameter to communicate what method to
use.  Personally, I would choose to limit it to POST.

Darrel

---

From: mike amundsen <[email-masked]>
Date: Fri, 1 Feb 2013 17:17:50 -0500

1 - This describes a use-case that is pretty rare in my work (an unsafe,
non-idempotent, empty request for a single protocol).

2 - It's not something I am likely to require in a media type design or in
an instance implementation. And if I did, it would proly be an
application-specific use-case; one that i'd solve within the available
media types themselves.

3 - Most all media types i deal w/ allow this already and i don't see an
advantage to create a rel value for it.

4 - I am not a fan of rel values that define protocol-level actions (e.g.
methods) anyway.

That's my view.

mamund
+1.859.757.1449
skype: mca.amundsen

On Fri, Feb 1, 2013 at 5:05 PM, Darrel Miller <[email-masked]>wrote:

>> so, "action" is only for sending an empty HTTP.POST request; nothing
>> else. no other protocol use (XMPP, WS, FTP, etc.) no HTTP.PUT, PATCH,
>> DELETE, or any other method that might be added to HTTP in the future,
>> correct?
>>
>>
>>

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Sat, 2 Feb 2013 02:45:54 +0400

Mike,

> 2 - It's not something I am likely to require in a media type design or in an instance implementation. And if I did, it would proly be an application-specific use-case; one that i'd solve within the available media types themselves. 

The approach i'm trying to defend doesn't require media type(s), message constructions etc... There are a lot of use cases where such kind of simple interactions just work and most of the interaction can be carried with simple HTTP messages + Link header field. This is the point of this link rel, not that it's impossible to implement such functionality with existing media types.

> 3 - Most all media types i deal w/ allow this already and i don't see an advantage to create a rel value for it.

Can you please point me to such media type which allows to implement similar functionality single-handedly? (i'm really interested).

> That's my view.

Thanks! :-)

Cheers,
ioseb

On Saturday, February 2, 2013 at 2:17 AM, mike amundsen wrote:

> 
> 1 - This describes a use-case that is pretty rare in my work (an unsafe, non-idempotent, empty request for a single protocol).
> 
> 2 - It's not something I am likely to require in a media type design or in an instance implementation. And if I did, it would proly be an application-specific use-case; one that i'd solve within the available media types themselves.  
> 
> 3 - Most all media types i deal w/ allow this already and i don't see an advantage to create a rel value for it.
> 
> 4 - I am not a fan of rel values that define protocol-level actions (e.g. methods) anyway. 
> 
> That's my view.
> 
> mamund
> +1.859.757.1449
> skype: mca.amundsen
> On Fri, Feb 1, 2013 at 5:05 PM, Darrel Miller <[email-masked] (mailto:[email-masked])> wrote:
> > Mike,
> > 
> > On Fri, Feb 1, 2013 at 4:51 PM, mike amundsen <[email-masked] (mailto:[email-masked])> wrote:
> > If another protocol has an equivalent operation which is unsafe and requires no parameters, then  I see no reason why there cannot be a mapping for that protocol.  However, for HTTP the only other method I can imagine that might map is DELETE.  However, that would then require the specification of a link-extension parameter to communicate what method to use.  Personally, I would choose to limit it to POST. 
> > 
> > Darrel 
> >  
> > 
> > 
> > 
> > 
> > 
> 
> 
>

---

From: mike amundsen <[email-masked]>
Date: Fri, 1 Feb 2013 18:13:23 -0500

On Fri, Feb 1, 2013 at 5:45 PM, Ioseb Dzmanashvili <
[email-masked]> wrote:

> Mike,
>
> > 2 - It's not something I am likely to require in a media type design or
> in an instance implementation. And if I did, it would proly be an
> The approach i'm trying to defend doesn't require media type(s), message
> constructions etc... There are a lot of use cases where such kind of simple
> interactions just work and most of the interaction can be carried with
> simple HTTP messages + Link header field. This is the point of this link
> rel, not that it's impossible to implement such functionality with existing
> media types.
>

well "there are lots" is most likely an exercise of availability bias :) I
am telling you here that "It's not something *I* am likely to require..."
not making a statement about your work or anyone else's work.

"simple HTTP messages" is also not quantifiable. I have no doubt you like
this design; might even find it to be "simple" I'm not saying it's "not
simple." maybe you have another thing in mind for "simple" that i'm not
getting here.

We agree "it's not impossible... with existing media types" - no problem
there.

> Can you please point me to such media type which allows to implement
> similar functionality single-handedly? (i'm really interested).
>
"single-handedly" is something I can't comment upon since i don't know what
you mean here.

however, i can describe an "empty POST" in HTML, HAL, Cj, and Siren; proly
voiceXML, too. Atom doesn't support any variable definitions for unsafe
transitions (empty or otherwise), but OData's CDSL allows me to describe an
empty POST.

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Sat, 2 Feb 2013 03:44:18 +0400

Mike,

> "simple HTTP messages" is also not quantifiable. I have no doubt you like this design; might even find it to be "simple" I'm not saying it's "not simple." maybe you have another thing in mind for "simple" that i'm not getting here.

Well, what i mean under "simple" is this: having link relation type like "action" which has very clear and simple purpose(i.e. send an empty POST request to this URI), it's very easy to filter out these "action" links from bunch of other links and present to the application user contextually(i.e. actions available alongside list items, window/page/screen level actions etc...) without need to rely on:

* Application level semantics which are described in underlying media type;
* Application specific conventions;
* Additional documentation;
* Some other assumptions;
* etc...

As i see it it's mostly useful for applications where users are involved and less valuable for M2M interactions(though it's possible too).

Under "simple HTTP messages" i mean that HTTP headers and status codes could be enough in lots of cases.

> "single-handedly" is something I can't comment upon since i don't know what you mean here.

Sorry for confusion, i meant without involving media types help to describe such kind of interactions.

> however, i can describe an "empty POST" in HTML, HAL, Cj, and Siren; proly voiceXML, too. Atom doesn't support any variable definitions for unsafe transitions (empty or otherwise), but OData's CDSL allows me to describe an empty POST.

I do not argue that it's not possible with mentioned formats, and to be honest i do it all time. Though there are some cons when using these media types for describing these unsafe interactions. To be clear, HTML allows us to construct messages the way we want(i.e. inline empty forms, links, data...), this format is very well understood by browsers and can be rendered properly according to its structure. 

On the other hand not HAL nor Cj have such possibilities(i.e rendering). These formats do not offer such possibility to directly embed multiple "forms" for constructing empty POST requests. Even it's achievable it doesn't clearly say how to distinguish such elements from the document. Whereas links(which both formats support fantastically) could be easily distinguished and grouped from others by rel values and presented contextually to users.

Again, it's not that there is no possibility for doing such things but in my opinion it's not that simple and clear.

Best regards,
ioseb

On Saturday, February 2, 2013 at 3:13 AM, mike amundsen wrote:

> On Fri, Feb 1, 2013 at 5:45 PM, Ioseb Dzmanashvili <[email-masked] (mailto:[email-masked])> wrote:
> > Mike,
> > 
> well "there are lots" is most likely an exercise of availability bias :) I am telling you here that "It's not something *I* am likely to require..." not making a statement about your work or anyone else's work. 
> 
> "simple HTTP messages" is also not quantifiable. I have no doubt you like this design; might even find it to be "simple" I'm not saying it's "not simple." maybe you have another thing in mind for "simple" that i'm not getting here. 
> 
> We agree "it's not impossible... with existing media types" - no problem there.
> 
> > 
> "single-handedly" is something I can't comment upon since i don't know what you mean here. 
> 
> however, i can describe an "empty POST" in HTML, HAL, Cj, and Siren; proly voiceXML, too. Atom doesn't support any variable definitions for unsafe transitions (empty or otherwise), but OData's CDSL allows me to describe an empty POST. 
>  
> > 
> > > That's my view.
> > 
> > Thanks! :-)
> > 
> > Cheers,
> > ioseb
> > 
> >

---

From: Darrel Miller <[email-masked]>
Date: Fri, 1 Feb 2013 18:45:09 -0500

Mike,

> transitions (empty or otherwise), but OData's CDSL allows me to describe an

Unless, Mr. Kelly did some magic on HAL while I wasn't looking there is
nothing in the media type that allows you to include hypermedia controls
for unsafe interactions without deferring to a link relation.

Also, OData has also come to the same conclusion that the concept of an
"action" is necessary, which is why they invented OData "Actions".
http://www.odata.org/blog/2011/10/7/actions-in-odata

Darrel

---

From: mike amundsen <[email-masked]>
Date: Fri, 1 Feb 2013 18:46:49 -0500

Darrel:

did you just make a case for the abiltiy to do unsafe non-idempotent empty
requests in OData and HAL w/o using this new rel value?

mamund
+1.859.757.1449
skype: mca.amundsen

On Fri, Feb 1, 2013 at 6:45 PM, Darrel Miller <[email-masked]>wrote:

>> however, i can describe an "empty POST" in HTML, HAL, Cj, and Siren;
>> proly voiceXML, too. Atom doesn't support any variable definitions for
>> unsafe transitions (empty or otherwise), but OData's CDSL allows me
>> to describe an empty POST.
>>
>>
>

---

From: mike amundsen <[email-masked]>
Date: Fri, 1 Feb 2013 18:54:40 -0500

so, the primary reason for offering this is to be able to describe an
unsafe, non-idempotent empty transition using only message metadata (Link
header), right?

mamund
+1.859.757.1449
skype: mca.amundsen

On Fri, Feb 1, 2013 at 6:44 PM, Ioseb Dzmanashvili <
[email-masked]> wrote:

> Mike,
>
> > "simple HTTP messages" is also not quantifiable. I have no doubt you
> like this design; might even find it to be "simple" I'm not saying it's
> "not simple." maybe you have another thing in mind for "simple" that i'm
> not getting here.
>
> Well, what i mean under "simple" is this: having link relation type like
> "action" which has very clear and simple purpose(i.e. send an empty POST
> request to this URI), it's very easy to filter out these "action" links
> from bunch of other links and present to the application user
> contextually(i.e. actions available alongside list items,
> window/page/screen level actions etc...) without need to rely on:
>
> As i see it it's mostly useful for applications where users are involved
> and less valuable for M2M interactions(though it's possible too).
>
> unsafe transitions (empty or otherwise), but OData's CDSL allows me to
> describe an empty POST.
>
> I do not argue that it's not possible with mentioned formats, and to be
> honest i do it all time. Though there are some cons when using these media
> types for describing these unsafe interactions. To be clear, HTML allows us
> to construct messages the way we want(i.e. inline empty forms, links,
> data...), this format is very well understood by browsers and can be
> rendered properly according to its structure.
>
> On the other hand not HAL nor Cj have such possibilities(i.e rendering).
> These formats do not offer such possibility to directly embed multiple
> "forms" for constructing empty POST requests. Even it's achievable it
> doesn't clearly say how to distinguish such elements from the document.
> Whereas links(which both formats support fantastically) could be easily
> distinguished and grouped from others by rel values and presented
> contextually to users.
>
> Again, it's not that there is no possibility for doing such things but in
> my opinion it's not that simple and clear.
>
> Best regards,
> ioseb
>
>

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Sat, 2 Feb 2013 03:58:27 +0400

Mike,

Let me ask question before Darrel responds.

> Darrel:
> did you just make a case for the abiltiy to do unsafe non-idempotent empty requests in OData and HAL w/o using this new rel value?

How this thing:

<m:action rel="http://otherserver/$metadata#MyEntities.Checkout" 
          target="Movies(6)/Checkout" 
          title="Checkout Donnie Darko" />

is different from: Link: <Movies(6)/Checkout>; rel="action http://otherserver/$metadata#MyEntities.Checkout"; title="Checkout Donnie Darko"

Other than it's a part of the media type itself and is not directly useful outside the OData format?

Also, how it's possible to implement this in HAL without introducing some additional structure(extending the format or introducing some specific convention on particular application implementation level)

Cheers,
ioseb

On Saturday, February 2, 2013 at 3:46 AM, mike amundsen wrote: 
> Darrel:
> 
> did you just make a case for the abiltiy to do unsafe non-idempotent empty requests in OData and HAL w/o using this new rel value?
> 
> mamund
> +1.859.757.1449
> skype: mca.amundsen
> On Fri, Feb 1, 2013 at 6:45 PM, Darrel Miller <[email-masked] (mailto:[email-masked])> wrote:
> > 
> > Mike,
> > 
> > On Fri, Feb 1, 2013 at 6:13 PM, mike amundsen <[email-masked] (mailto:[email-masked])> wrote:
> > > 
> > Unless, Mr. Kelly did some magic on HAL while I wasn't looking there is nothing in the media type that allows you to include hypermedia controls for unsafe interactions without deferring to a link relation. 
> > 
> > Also, OData has also come to the same conclusion that the concept of an "action" is necessary, which is why they invented OData "Actions".  http://www.odata.org/blog/2011/10/7/actions-in-odata 
> > 
> > 
> > Darrel
> > 
> > 
> >

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Sat, 2 Feb 2013 04:01:51 +0400

Mike,

> so, the primary reason for offering this is to be able to describe an unsafe, non-idempotent empty transition using only message metadata (Link header), right?

No of course, it can be used in other formats too i believe. 

ioseb 

On Saturday, February 2, 2013 at 3:54 AM, mike amundsen wrote:

> so, the primary reason for offering this is to be able to describe an unsafe, non-idempotent empty transition using only message metadata (Link header), right?
> 
> mamund
> +1.859.757.1449
> skype: mca.amundsen
> On Fri, Feb 1, 2013 at 6:44 PM, Ioseb Dzmanashvili <[email-masked] (mailto:[email-masked])> wrote:
> > Mike,
> >

---

From: mike amundsen <[email-masked]>
Date: Fri, 1 Feb 2013 19:05:41 -0500

On Fri, Feb 1, 2013 at 6:58 PM, Ioseb Dzmanashvili <
[email-masked]> wrote:

> > did you just make a case for the abiltiy to do unsafe non-idempotent
> empty requests in OData and HAL w/o using this new rel value?
>
> How this thing:
>
> is different from: Link: <Movies(6)/Checkout>; rel="action
> http://otherserver/$metadata#MyEntities.Checkout"; title="Checkout Donnie
> Darko"
>

> outside the OData format?

Since one of your key cases is that your proposal bypasses describing the
transition within a message body, I suppose the only difference is the one
you think is important, right?

>
> Also, how it's possible to implement this in HAL without introducing some
> additional structure(extending the format or introducing some specific
> convention on particular application implementation level)
>

In my (limited) use of HAL, all transition semantics (methods, bodies,
etc.) are supplied in human readable documentation and associated w/ a rel
value. I just write documentation that sez pass no arguments in the body,
method=POST and associate that w/ my selected link rel value.

---

From: mike amundsen <[email-masked]>
Date: Fri, 1 Feb 2013 19:06:11 -0500

> No of course, it can be used in other formats too i believe.

other formats such as in media type bodies? as in the examples I already
supplied? or something else?

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Sat, 2 Feb 2013 04:11:10 +0400

Mike,

> other formats such as in media type bodies? as in the examples I already supplied? or something else?

Yes. Below is the example I posted to this thread in earlier messages:
-----------------------

{"document": {
"href": "/posts"
"links": {
"item": [{
"href": "/posts/1",

ioseb 

On Saturday, February 2, 2013 at 4:06 AM, mike amundsen wrote:

> On Fri, Feb 1, 2013 at 7:01 PM, Ioseb Dzmanashvili <[email-masked] (mailto:[email-masked])> wrote:
> > Mike,
> > 
> other formats such as in media type bodies? as in the examples I already supplied? or something else?
> 
> > 
> > ioseb
> >

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Sat, 2 Feb 2013 04:14:53 +0400

Mike,

> Since one of your key cases is that your proposal bypasses describing the transition within a message body, I suppose the only difference is the one you think is important, right?

"bypassing" message body is one of the possibilities and this we get for free because of Link header field, in other response i posted another example where "action" links are embedded in body. Another option is that existence of well defined link relation makes it reusable in different implementation without the need to redefine "action" semantics or rely on some specific human readable documentation(which is not reusable across organisations for example).

ioseb 

On Saturday, February 2, 2013 at 4:05 AM, mike amundsen wrote:

> On Fri, Feb 1, 2013 at 6:58 PM, Ioseb Dzmanashvili <[email-masked] (mailto:[email-masked])> wrote:
> > Mike,
> > 
> Since one of your key cases is that your proposal bypasses describing the transition within a message body, I suppose the only difference is the one you think is important, right?
>  
> > 
> In my (limited) use of HAL, all transition semantics (methods, bodies, etc.) are supplied in human readable documentation and associated w/ a rel value. I just write documentation that sez pass no arguments in the body, method=POST and associate that w/ my selected link rel value. 
> 
> > 
> > Cheers,
> > ioseb
> >

---

From: Darrel Miller <[email-masked]>
Date: Fri, 1 Feb 2013 19:29:42 -0500

Mike,

> requests in OData and HAL w/o using this new rel value?
For sure.  We can mint rel="print", rel="start", rel="stop", rel="restart",
rel="launch", rel="publish", rel="submit", rel ="poke", rel="like", rel="+1"

and in our client code we can do

if (userClickedAButton and rel in ("print", "start", "stop", "restart",
"launch", "publish", "submit", "poke", "like") {

   httpClient.Post(targetUrl, null)

}

<currentState>Tongue planted firmly in cheek</currentState>

Darrel

---

From: mike amundsen <[email-masked]>
Date: Fri, 1 Feb 2013 20:11:02 -0500

Well, I've taken a couple passes at working to expose the unique value of
this proposed link rel value and haven't found it. At this point, my Qs
have come full circle.

For me, what you describe remains a narrowly-focused use case which I
rarely encounter (generic description of empty POST) and when I
do encounter the need, I find I have more than enough options already
available to me.

You guys are welcome to it.

Cheers.

mamund
+1.859.757.1449
skype: mca.amundsen

On Fri, Feb 1, 2013 at 7:29 PM, Darrel Miller <[email-masked]>wrote:

> For sure.  We can mint rel="print", rel="start", rel="stop",
> rel="restart", rel="launch", rel="publish", rel="submit", rel ="poke",
> rel="like", rel="+1"
>

---

From: Jan Algermissen <[email-masked]>
Date: Sat, 2 Feb 2013 07:26:59 +0100

On 02.02.2013, at 01:29, Darrel Miller <[email-masked]> wrote:

> 
> 
> For sure.  We can mint rel="print", rel="start", rel="stop", rel="restart", rel="launch", rel="publish", rel="submit", rel ="poke", rel="like", rel="+1"
> 

What happened to the idea that REST means 'representational state transfer' and not 'remote method invocation'?

Jan

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Sat, 2 Feb 2013 15:40:30 +0400

Thank you very much Mike!

ioseb 

On Saturday, February 2, 2013 at 5:11 AM, mike amundsen wrote:

> Well, I've taken a couple passes at working to expose the unique value of this proposed link rel value and haven't found it. At this point, my Qs have come full circle.
> 
> For me, what you describe remains a narrowly-focused use case which I rarely encounter (generic description of empty POST) and when I do encounter the need, I find I have more than enough options already available to me. 
> 
> On Fri, Feb 1, 2013 at 7:29 PM, Darrel Miller <[email-masked] (mailto:[email-masked])> wrote:
> > Mike,
> > 
> > 
> > On Fri, Feb 1, 2013 at 6:46 PM, mike amundsen <[email-masked] (mailto:[email-masked])> wrote:
> > > Darrel:
> > > 
> > if (userClickedAButton and rel in ("print", "start", "stop", "restart", "launch", "publish", "submit", "poke", "like") { 
> >

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Sat, 2 Feb 2013 15:56:58 +0400

Hi Jan,

> What happened to the idea that REST means 'representational state transfer' and not 'remote method invocation'?

Sorry for not giving up on this, but i've few questions. I do not want to dive into REST details, but from REST description, representation is a sequence of bytes + meta data. From both, REST and HTTP PoV i do not see(or maybe do not understand?) why "Representaiontal" part of the style is violated? 

This is the quote from Fielding's dissertation:

> What makes HTTP significantly different from RPC is that the requests are directed to resources using a generic interface with standard semantics that can be interpreted by intermediaries almost as well as by the machines that originate services

What do we violate here? is there any restriction which prevents us from defining processing resources?

cheers,
ioseb

On Saturday, February 2, 2013 at 10:26 AM, Jan Algermissen wrote:

> 
> On 02.02.2013, at 01:29, Darrel Miller <[email-masked] (mailto:[email-masked])> wrote:
> 
> > 
> >

---

From: Jan Algermissen <[email-masked]>
Date: Sat, 2 Feb 2013 14:50:53 +0100

> Sorry for not giving up on this, but i've few questions. I do not want to dive into REST details, but from REST description, representation is a sequence of bytes + meta data. From both, REST and H…

You are not transferring state to advance the application, you are effectively invoking a non-uniform method (e.g. 'publish')

You are not even doing a POST in the sense 'take this data and do with it as you please'.

And for some of your desired cases you are even loosing the visibility a use of PUT would give you. It's effectively RPC, IMHO.

Jan

---

From: Darrel Miller <[email-masked]>
Date: Sat, 2 Feb 2013 12:54:50 -0500

How about we work with a pseudo real example.  I'm building a home
automation system.  I have various devices that I want to write clients for
that will allow me to interact with "resources" in my home.

After several link traversals from the the API root I end up doing one of
these requests depending on the client device.

> GET /home/livingroom/lights/northcorner
> Accept:  application/hal+xml

< 200 OK

<resource href="/home/livingroom/lights/northcorner">
   <name>North Corner</name>
   <room>Living Room</room>
   <lightStyle>Recessed Pot Light</lightStyle>
   <bulbType>Par20</bulbType>
   <lastChanged>2012-01-07</lastChanged>
   <currentState>On</currentState>
</resource>

> GET /home/livingroom/lights/northcorner
> Accept:  text/plain

< 200 OK
< Content-Type: text/plain

North Corner light in living room
Recessed Pot Light using Par20 bulb
Bulb last changed 2012-01-07
Currently On.

> GET /home/livingroom/lights/northcorner
> Accept:  text/plain

< 200 OK
< Content-Type: text/html
<html>
<body>
<p>North Corner light in living room</p>
<p>Recessed Pot Light using Par20 bulb</p>
<p>Bulb last changed 2012-01-07</p>
<p>Currently On.</p>
</body>
</html>

Using either a an embedded link (hal), a link header (plain/text),  or an
empty form with POST method I can easily augment these representations to
make it simple for a client to present the user with an option to change
the state of the light using no other knowledge than how to make a POST
request.

Can you explain to me how these clients would be able to achieve this with
PUT?

Darrel

On Sat, Feb 2, 2013 at 8:50 AM, Jan Algermissen
<[email-masked]>wrote:

> > > What happened to the idea that REST means 'representational state
> transfer' and not 'remote method invocation'?
> >
> > Sorry for not giving up on this, but i've few questions. I do not want
> to dive into REST details, but from REST description, representation is a
> sequence of bytes + meta data. From both, REST and HTTP PoV i do not see(or
> maybe do not understand?) why "Representaiontal" part of the style is
> violated?
>
> You are not transferring state to advance the application, you are
> effectively invoking a non-uniform method (e.g. 'publish')
>
> And for some of your desired cases you are even loosing the visibility a
> use of PUT would give you. It's effectively RPC, IMHO.
>
> Jan
>
>
> >
> >> What makes HTTP significantly different from RPC is that the requests
> are directed to resources using a generic interface with standard semantics
> that can be interpreted by intermediaries almost as well as by the machines
> that originate services
> >> What happened to the idea that REST means 'representational state
> transfer' and not 'remote method invocation'?
> >>
> >>
> >> Jan
> >
>

---

From: Bjartur Thorlacius <[email-masked]>
Date: Sat, 2 Feb 2013 19:01:41 +0000

I think the point of the criticism is that either it replaces

DELETE /sample HTTP/1.0

with

POST /sample?delete HTTP/1.0

that is, uses e.g. the query component, a string of information to be
interpreted by the resource, to convey the action and the HTTP method
exclusively to convey the characteristics of the action (e.g.
idempotence), or worse, depends on context for semantics.

The purpose of the proposal is that of the HTTP header Options, plus
allowing private or "ad-hoc" methods.

Theoretically, separating information about method characteristics is
a good thing. But many want this to be done without cluttering
identifiers. Although technically, /sample?delete is quite obviously
an identifier for the action of deleting /sample. Deriving /sample
from the action URI/IRI is trivial to do and already specified in a
RFC. But it would be even better do convey the action in a separate
HTTP field.

---

From: Ioseb Dzmanashvili <[email-masked]>
Date: Mon, 11 Feb 2013 02:31:27 +0400

Hi Jan,

> You are not even doing a POST in the sense 'take this data and do with it as you please'.

Here is what HTTPBis says: "The actual function performed by the POST method is determined by the server and is usually dependent on the effective request URI." [1]

and if i'm not wrong "dependent on the effective request URI" is the key here. As far as sending an "empty" POST requests are not prohibited and function performed is determined by the server and depends on the effective request URI how do we violate uniformity? 

Below are several quotes from Roy Fielding: 

"Note that POST, regardless of which meaning is being used, has none of the characteristics that would make it useful for the architecture to know exactly what is going on". [2]

In the same post he defines POST method as "append-this" and POST method as "process-this". And says:

"POST(a), as "append this", is unsafe, non-idempotent, non-cacheable, operates on an unknown resource, and has only minor visibility since there is no way for an intermediary to anticipate the state of the resource after the append aside from "some state was added". POST(p), as "process this", doesn't even have that minor visibility. Thus, an architectural style like REST can only improve the performance of a POST-based architecture by finding ways to escape POST (e.g., 201)." [2]

If POST doesn't have visibility and performed function is dependent on the request URI and no one can know in advance what will be performed:

1) how is it possible to invoke non-uniform method?
2) in what sense it's RPC?
3) and how this is different compared to including same information in the entity body and asking server to do something? 

> And for some of your desired cases you are even loosing the visibility a use of PUT would give you. It's effectively RPC, IMHO.

I do not understand how PUT can help in this case.

[1]. http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-21#section-5.3.3
[2]. http://tech.groups.yahoo.com/group/rest-discuss/message/4732?threaded=1&p=5

Best regards,
ioseb

On Saturday, February 2, 2013 at 5:50 PM, Jan Algermissen wrote:

> 
> On 02.02.2013, at 12:56, Ioseb Dzmanashvili <[email-masked] (mailto:[email-masked])> wrote:
> 
> > Hi Jan,
> >