Re: [apps-discuss] NEW RELATION: 'action' version update

[Jan Algermissen <[e-mail]>]

On 28.08.2013, at 21:38, Ioseb Dzmanashvili <[e-mail]> wrote:

> 
> As a conclusion:
> 
> 1. Having the generic "action" relation is worthless, at list as of 00 and 01 proposals. At least i need to find better way to make it acceptable.

Hmm, I recall trying to tell you that in 00 ?

> 2. Action type registry complicates things(and i agree).
> 3. One possible way is to maintain separate registry(out of IETF) which is not feasible for me.
> 4. Most realistic is to register top level action link rels and i've several such relations:
> 
> - start: start service or process
> - stop: stop service or process
> - restart: restart service or process
> - suspend: suspend service or process
> - reset: reset service or process to its initial state

I'd say this is a domain (sending controll messages to control some 'thing') where REST isn't a particulary good fit. These operations expose a lot of implementation details - something that REST aims to hide. Or, IOW, using REST to design a control interface will not make you and the RESTafarians happy at the same time :-)

Suggestions:

- Build an unRESTful HTTP interface to avoid now uncool RPC solutions :-)  You know the story .... POST /jobs/start
 (Quite some things out there have such APIs, e.g. App servers, app engines,..)

- Hide the implementation details and think more in terms of what the client wants (I mean, who cares whether there is a job and that that can be suspended? Why would a service let a client start/stop/suspend anything it controls itself? IOW, talk about your domain, not the implementation

- Use a sort-of-restful solution by changing state of a status resource :

PUT /jobs/67/mode

<stoped/>

- or create a resource that the service provides for clients to change it's own internals vi an indirection. Much like you can edit a crontab, but not send a command to cron to suspend a job

POST /suspension-schedules

<suspensionSchedule>
  <workflow id="process-images"/>
 <time>some datetime afetr which to suspend</time>
</suspension>

.... nice candidate to re-use iCalender, BTW.

> 
> - publish: change state of the resource to published
> - unpublish: change state of the resource to unpublished
> - archive: change state of the resource to archived
> - unarchive: change state of the resource to unarchived
> 



> - enable: change state of the resource to enabled
> - disable: change state of the resource to disabled
> 

Which are all resource-state changes, too as you write yourself :-) Also, maybe these are not states but memberships in collection (e.g. move from draft to published queue/collection).


> These are actions i used frequently in various applications.

If it is an action, it is an implementation detail :-)

> Do you think it is reasonable to register all of these as link relations?
> 

Erm, no .... but you know that already ;-)

> Folks? What do you think?
> 

YAGNI...

Jan


> Cheers,
> ioseb
> 
>> .  
>> 
>> Cheers.
>> 
>> 
>> mamund
>> +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 Wed, Aug 28, 2013 at 12:41 PM, Ioseb Dzmanashvili <[e-mail] (mailto:[e-mail])> wrote:
>>> Mike,
>>> 
>>> On Wednesday, August 28, 2013 at 6:33 PM, mike amundsen wrote:
>>>> Ioseb:
>>>> 
>>>> now that i understand your aim...
>>>> 
>>>> it seems the first item (support a pattern...) is the important one and the other two are just means to that end.
>>> Actually as i see it #1 and #2 are of same importance.
>>> 
>>> 
>>>> so why is this a good approach?
>>> #1 and #2 still hold. As i already said #3 makes sense only for m2m scenarios and for GUI clients just knowing that a link is an action and how to treat such action links is enough.
>>> 
>>> What i'm trying to achieve with my proposal is to generalise meaning of action and make it consistent across different applications. Unfortunately i do not see(or know, or was not able to find) better approach yet but it is generic enough to solve whole class of problems at least on GUI level + partially for m2m cases with "action-type" attribute even if we throw action type registry idea away. If we simplify definition of the "action" relation type and say:
>>> 
>>> 1. here is the "action" link
>>> 2. it points to a resource which describes the action
>>> 3. to perform an action fetch it construct request and send it back to server.
>>> 4. if you want to know what this particular action means:
>>> 4.1. look inside the "action-type" attribute if it presents; or
>>> 4.2. fetch the document and look inside it.
>>> 
>>> Is not it sufficient enough to cover whole class of problems in a consistent way which are clearly actions and not just related resources?
>>> 
>>> So here is my question: why is it bad?
>>> 
>>>> 1) why use the "action" rel PLUS a param ("start")? why not just use the param ("start") as the rel?
>>> For several reasons:
>>> 
>>> 1. there is no "start" relation yet.
>>> 2. it doesn't have explicit sign that it is an action.
>>> 3. there are much more actions which are not registered and also there is no guarantee that each newly registered relation(which can be qualified as action) will state that it is an action in a consistent way.
>>> 4. the pattern as you noticed is still important(IMHO)
>>> 
>>>> 2) why not use two values for the rel as in <LINK rel="action start" />?
>>> 
>>> It was suggested in the initial proposal though approach has drawbacks. if i use more rels? <LINK rel="action foo bar baz" /> how to distinguish "foo", "bar" and "baz" from each other? does it mean that my action now has triple meaning?
>>> 
>>>> 3) why not use (as mike kelly suggests) an extension URI for the rel as in <LINK rel="http://actions.io/start" ... />
>>>> 
>>>> 4) why not use a unique element attribute/property such as <LINK rel="action" reason="start" .../>?
>>> 
>>> is it different from "action-type" attribute? or maybe problem is in a registry of action types?
>>> 
>>>> 5) why not use a unique document element/property such as <action rel="start" href="..."/> or {"action": {"rel":"start", "href":"..."}}?
>>> Well, in custom media types i can do anything, though it doesn't make sense outside of particular format or domain. Otherwise it is ok and i use similar approach in practice.
>>> 
>>> Cheers,
>>> ioseb
>>> 
>>>> 
>>>> mamund
>>>> +1.859.757.1449 (tel:%2B1.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 Wed, Aug 28, 2013 at 3:35 AM, Ioseb Dzmanashvili <[e-mail] (mailto:[e-mail]) (mailto:[e-mail]) (mailto:[e-mail])> wrote:
>>>>> Mike,
>>>>> 
>>>>> On Wednesday, August 28, 2013 at 5:26 AM, mike amundsen wrote:
>>>>> 
>>>>>> OK, from your response i get the following:
>>>>>> 
>>>>>> 1) you want to support a pattern where machine-readable state transition instructions appear at the end of some URL.
>>>>>> 2) you want to indicate those instructions are available by marking the URL w/ the string literal "action" (via rel in your illustrations)
>>>>>> 3) you want to indicate the reason for using these instructions w/ an "action-type" string (via a link-rel param in your illustrations)
>>>>>> 
>>>>>> that's it. nothing else.
>>>>>> 
>>>>>> do i have this correct?
>>>>> 
>>>>> Exactly! That's it and nothing else.
>>>>> 
>>>>> Cheers,
>>>>> ioseb
>>>>> 
>>>>>> 
>>>>>> 
>>>>>> mamund
>>>>>> +1.859.757.1449 (tel:%2B1.859.757.1449) (tel:%2B1.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 Tue, Aug 27, 2013 at 7:51 PM, Ioseb Dzmanashvili <[e-mail] (mailto:[e-mail]) (mailto:[e-mail]) (mailto:[e-mail]) (mailto:[e-mail])> wrote:
>>>>>>> Hi Mike,
>>>>>>> 
>>>>>>> Thanks for the question!
>>>>>>> 
>>>>>>> On Tuesday, August 27, 2013 at 11:57 PM, mike amundsen wrote:
>>>>>>> 
>>>>>>>> Ioseb:
>>>>>>>> 
>>>>>>>> it is not clear to me why: <link rel="action;action-type='edit'" href="..." />
>>>>>>>> is preferable to: <link rel="edit" href="..." />
>>>>>>>> 
>>>>>>>> talk me down ;)
>>>>>>> let me try ;)
>>>>>>> 
>>>>>>> Question is not about why: Link: <…>; rel="action"; action-type="edit" is preferable to: Link: <…>; rel="edit".
>>>>>>> 
>>>>>>> Of course i'd choose rel="run-forest-run" if there is a registered link relation type, but:
>>>>>>> 
>>>>>>> 1. The "action" link relation is generic enough, has well understood meaning and is useful on its own especially for human oriented agents.
>>>>>>> 2. The "action-type" optional attribute may be used for specifying exact meaning of actions and this makes action links more useful for m2m scenarios.
>>>>>>> 
>>>>>>> Now consider this link:
>>>>>>> 
>>>>>>> Link: </suspend-action>; rel="action"; action-type="suspend"; title="Suspend"
>>>>>>> 
>>>>>>> What it says?
>>>>>>> 
>>>>>>> 1. it is an action
>>>>>>> 2. target resource represents description of the action which contains: request method, submit URI, definition of action, other details etc
>>>>>>> 3. agent can look inside "action-type" to determine whether it needs this action type or not
>>>>>>> 4. agent can dereference it, construct request and send it to server
>>>>>>> 
>>>>>>> 
>>>>>>> now if we add more actions:
>>>>>>> 
>>>>>>> Link: </suspend-action>; rel="action"; action-type="suspend"; title="Suspend"
>>>>>>> Link: </restart-action>; rel="action"; action-type="restart"; title="Restart"
>>>>>>> 
>>>>>>> Link: </stop-action>; rel="action"; action-type="stop"; title="Stop"
>>>>>>> 
>>>>>>> 
>>>>>>> #1, #2, #3 and #4 will be true for all of them without exceptions.
>>>>>>> 
>>>>>>> Now consider that representation containing these links is used by GUI agent, in this case even "action-type" is not necessary at all and agent can rely on user's choice. Agent only needs to know that:
>>>>>>> 
>>>>>>> 1. link is an action(and this question is explicitly answered)
>>>>>>> 2. if user choose one agent needs just to dereference indicated URI
>>>>>>> 3. construct request
>>>>>>> 4. send request to server
>>>>>>> 5. show results to user
>>>>>>> 
>>>>>>> All of these will remain true for any action type.
>>>>>>> 
>>>>>>> I'm not sure if i talked you down, but i believe "action" relation type is useful and not because it is better(or simpler) compared to rel="edit" for example.
>>>>>>> 
>>>>>>> 1. http://tools.ietf.org/html/draft-ioseb-dzmanashvili-action-link-relation-00
>>>>>>> 2. http://tools.ietf.org/html/draft-ioseb-dzmanashvili-action-link-relation-01
>>>>>>> 
>>>>>>> P.S.
>>>>>>> I was talking about 01 version of spec. 00 is a different story.
>>>>>>> 
>>>>>>> Cheers,
>>>>>>> ioseb
>>>>>>>> mamund
>>>>>>>> +1.859.757.1449 (tel:%2B1.859.757.1449) (tel:%2B1.859.757.1449) (tel:%2B1.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 Tue, Aug 27, 2013 at 3:40 PM, Ioseb Dzmanashvili <[e-mail] (mailto:[e-mail]) (mailto:[e-mail]) (mailto:[e-mail]) (mailto:[e-mail]) (mailto:[e-mail]) (mailto:[e-mail])> wrote:
>>>>>>>>> Hi Julian,
>>>>>>>>> 
>>>>>>>>> Thanks for response!
>>>>>>>>> 
>>>>>>>>> On Tuesday, August 27, 2013 at 2:15 PM, Julian Reschke wrote:
>>>>>>>>> 
>>>>>>>>>> On 2013-08-27 11:03, Ioseb Dzmanashvili wrote:
>>>>>>>>>>> Hi All,
>>>>>>>>>>> 
>>>>>>>>>>> I've updated the "action" link relation type spec[1] based on initial feedback.
>>>>>>>>>>> 
>>>>>>>>>>> As far as initial reactions were very controversial and raised a lot of issues i tried to address all of them and entirely changed the spec.
>>>>>>>>>>> 
>>>>>>>>>>> ==================================================
>>>>>>>>>>> When included in a response, the "action" link relation indicates a
>>>>>>>>>>> target resource that is responsible for performing action which MAY:
>>>>>>>>>>> 
>>>>>>>>>>> - Affect state of the context resource; or
>>>>>>>>>>> - Initiate process.
>>>>>>>>>>> 
>>>>>>>>>>> The "action" link relation type can be used to indicate the
>>>>>>>>>>> availability of actions supported by the target resource. Examples
>>>>>>>>>>> of such actions include:
>>>>>>>>>>> 
>>>>>>>>>>> - Enable/Disable
>>>>>>>>>>> - Publish/Unpublish
>>>>>>>>>>> - Start/Stop
>>>>>>>>>>> 
>>>>>>>>>>> The "action" link relation type doesn't convey any semantics other
>>>>>>>>>>> than that an indicated resources represent machine readable
>>>>>>>>>>> description of a particular action and representation SHOULD contain
>>>>>>>>>>> all necessary details such as: request method, action URI and other
>>>>>>>>>>> related details to enable agents to be able to construct requests
>>>>>>>>>>> without relying on out-of-band information.
>>>>>>>>>>> 
>>>>>>>>>>> Exact type of action SHOULD be indicated through the "action-type"
>>>>>>>>>>> link-extension value as per [RFC5988] and for maintaining shared
>>>>>>>>>>> understanding of action types current specification introduces the
>>>>>>>>>>> registry of actions with initial values of widely accepted and well
>>>>>>>>>>> understood action types.
>>>>>>>>>>> 
>>>>>>>>>>> For example, if a resource represents a service, that same
>>>>>>>>>>> representation may include links to resources that represent actions
>>>>>>>>>>> supported by the service:
>>>>>>>>>>> 
>>>>>>>>>>> Link: </restart-action>; rel="action"; action-type="restart"
>>>>>>>>>>> Link: </stop-action>; rel="action"; action-type="stop"
>>>>>>>>>>> ...
>>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>>> It seems that you are just adding an indirection mechanism. Why is that
>>>>>>>>>> necessary?
>>>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> With indirection mechanism i'm trying to solve issues raised around initial version of the spec[1]. There were several issues:
>>>>>>>>> 
>>>>>>>>> 1. The "action" link relation type doesn't have enough semantics and automated agents can not follow such links if there are several actions included in a representation. With the "action-type" link extension + registry of predefined action types agents can distinguish actions from each other.
>>>>>>>>> 
>>>>>>>>> 2. Initial spec stated that if the "action" link exists in representation, only thing agents should do is to send empty POST request to the target in order to perform action. This approach was considered as an anti pattern(RPCish and non RESTful). With having the "action-type" agents can:
>>>>>>>>> 
>>>>>>>>> a) distinguish action links from each other;
>>>>>>>>> b) if necessary dereference the target to obtain instructions for constructing non empty POST/PUT requests;
>>>>>>>>> c) send properly constructed request back to the target; and
>>>>>>>>> d) it makes possible for servers to dictate structure of the request according to there own needs.
>>>>>>>>> 
>>>>>>>>> Main purpose of the "action" link relation type is to define semantics of particular class of links - actions. This eliminates the need to redefine notion of "action" for each link relation type which may be qualified as action link. The "action-type" is just for naming actions and is particularly useful for automated agents not necessarily for human interaction oriented agents.
>>>>>>>>> 
>>>>>>>>> Having action type registry is important for maintaining shared understanding of particular action types. For example "reset" or "publish" verbs do not need to be redefined from application to application. I also believe that it is not efficient(or feasible) to register all possible actions as link relations.
>>>>>>>>> 
>>>>>>>>> 1. http://tools.ietf.org/html/draft-ioseb-dzmanashvili-action-link-relation-00
>>>>>>>>> 2. http://tools.ietf.org/html/draft-ioseb-dzmanashvili-action-link-relation-01
>>>>>>>>>> 
>>>>>>>>>> Best regards, Julian
>>>>>>>>> Cheers,
>>>>>>>>> ioseb
>>>>>>>>> 
>>>>>>>>> _______________________________________________
>>>>>>>>> link-relations mailing list
>>>>>>>>> [e-mail] (mailto:[e-mail]) (mailto:[e-mail]) (mailto:[e-mail]) (mailto:[e-mail]) (mailto:[e-mail]) (mailto:[e-mail])
>>>>>>>>> https://www.ietf.org/mailman/listinfo/link-relations
>>>>>>>>> 
>>>>>>>> 
>>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>> 
>>>>>> 
>>>>> 
>>>>> 
>>>> 
>>>> 
>>> 
>>> 
>> 
>> 
> 
> 
> 
> _______________________________________________
> apps-discuss mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/apps-discuss