[Oslc-Automation] Changes I have made to Actions specs based on Actions issues list
Martin P Pain
martinpain at uk.ibm.com
Fri Mar 14 06:26:51 EDT 2014
Ah, I think I see what you are getting at now.
I was thinking "if it's 200, it's completed", but I forgot that it can be
state=completed, but verdict=failed. (For some reason I was thinking
"failure" meant "incomplete", forgetting that if it has failed is has
"completed".)
I see the problem.
Do you think it would be appropriate in 2.1 to make the synchronous case
more "RESTful" (i.e. easier to integrate with things like the FB
interaction pattern) by saying that if it returns a verdict other than
"passed" (or perhaps "warning") that it returns a 5xx or 4xx status code?
(I believe they all permit a response body). WebDAV's 424 "Method Failure"
[1] [2] might be appropriate.
(This would mean that those implementations that use 2.0 synchronous
execution would not be compliant to 2.1 - so this might be more
appropriate for 3.0 than 2.1).
Or do you think it would be more appropriate to split the FB and AR
interaction patterns?
Any individual provider would still be free, I believe, to use a 4xx/5xx
return code in the synchronous AR case, as in the paragraph above, and so
use an AR as a fixed body, but it would have to explicitly make it
recognizable as both, rather than the spec doing so. I guess we can always
suggest it, or even make it a best practice, to support FB when using AR
(which should work fine with asynchronous execution, and the change above
can make it work with synchronous execution).
The only question for that approach is what is the recognition rule for
AR?
I feel like we should go with splitting the patterns, and documenting in
what cases you can use them together (I probably can't make a convincing
enough argument for making it a best practice - we can discuss whether any
profile should require both from providers), then propose for 3.0 that
synchronous execution returns a non-2xx code for failure.
[1] http://en.wikipedia.org/wiki/List_of_HTTP_status_codes#424
[2] http://msdn.microsoft.com/en-us/library/aa142868%28v=exchg.65%29.aspx
Martin Pain
Software Developer - Green Hat
Rational Test Virtualization Server, Rational Test Control Panel
Open Services for Lifecycle Collaboration - Automation WG joint chair
E-mail: martinpain at uk.ibm.com
Find me on: and within IBM on:
IBM United Kingdom Limited
Registered in England and Wales with number 741598
Registered office: PO Box 41, North Harbour, Portsmouth, Hants. PO6 3AU
"Oslc-Automation" <oslc-automation-bounces at open-services.net> wrote on
13/03/2014 17:29:41:
> From: John Arwe <johnarwe at us.ibm.com>
> To: oslc-automation at open-services.net,
> Date: 13/03/2014 17:30
> Subject: Re: [Oslc-Automation] Changes I have made to Actions specs
> based on Actions issues list
> Sent by: "Oslc-Automation" <oslc-automation-bounces at open-services.net>
>
> I think the trouble with inheriting from fixed body to automation
> request interaction pattern is how failures are detected by the
> client. But maybe I'm reading something into the spec that others
> are not. Think about the distinction (in Automation, but I don't
> think in Fixed Body) that must exist between success *of the HTTP
> request* (status code) and success *of the client's intent* aka the
> action's binding (which maps 1:1 to the HTTP request in the case of
> FB, but can differ in the case of AR). In particular, what happens
> when the HTTP request is successful but the action was NOT
> accomplished, which only Can Occur in the Auto Request IP I think.
>
> Example:
> Client goal: issue start command for JES2 (pick your favorite
> resource - doesn't matter).
>
> [It so happens that in this case, JES2 is currently in a state such
> that it cannot be started. All the requests below are destined to
> Fail. Take that as an assumption.]
> Client finds core:action > rdf:type=core:Action with bindings for
> fixed body and auto request (for simplicity here, two separate and disti
> Auto request: POST( auto-req ), 201 Location: AR1, GET AR1, 200 +
> state=complete verdict=failed
> Fixed body (no parameters, not an Automation-related pattern; use
> the CM pattern): POST, 4xx or 5xx response ... probably 409
> conflict, exact value doesn't matter. Point is, it CANNOT be 2xx
> (except 202) because it wasn't successful. If it's 202, HTTP is
> wide open (no interop) anyway.
> Fixed body (happens to use Auto Request): POST( auto-req ), 200
> ... how does the client know that it's supposed to look inside the
> representation (which might be opaque to it) for the verdict? I
> thought the point of having the fixed-body pattern is the body is
> opaque to the client.
> I took it on faith that when we christened things "interaction
> patterns" that we were, of necessity, admitting that sometimes the
> pattern necessary to accomplish the action requires more than one
> HTTP request. FB == 1 HTTP request in my thinking; AR is >=1.
> We've concentrated on the "everything works" cases too, so perhaps
> people had ideas about failure flows that don't align with what I
> have sketched out above. If so, let's get the other mental models
> rendered explicit.
> Best Regards, John
>
> Voice US 845-435-9470 BluePages
> Tivoli OSLC Lead - Show me the Scenario
>
>
>
>
> From: Martin P Pain <martinpain at uk.ibm.com>
> To: John Arwe/Poughkeepsie/IBM at IBMUS,
> Cc: oslc-automation at open-services.net, "Oslc-Automation"
> <oslc-automation-bounces at open-services.net>
> Date: 03/13/2014 12:54 PM
> Subject: Re: [Oslc-Automation] Changes I have made to Actions
> specs based on Actions issues list
>
>
>
> I see that as compatible with Actions Appendix A:
>
> http://open-services.net/wiki/core/Exposing-arbitrary-actions-on-
> RDF-resources/#constructing-http-requests
>
> 200 (OK) to indicate that the action has completed
>
> 201 (Created) to indicate that the request resulted in the creation
> of a new resource; the Location response header provides the URL of
> the newly created resource. The client is responsible for
> interrogating the resource’s state to determine whether or not the
> action has completed. One use of this in certain profiles is to use
> the OSLC Automation specification’s mechanisms to monitor its
> progress and success/failure.
>
> 202 (Accepted) to indicate that the request has been queued and will
> be dealt with at a later time, at which point it might succeed or fail.
>
>
>
> Do you see an incompatibility (here or elsewhere)? I don't see an AR
> returning 200 other than when it has "finished", which is the same
> as the FB case. (Or is it not the same?)
> Do we need to link to this from somewhere else in the spec to make it
clearer?
>
>
> Martin Pain
> Software Developer - Green Hat
> Rational Test Virtualization Server, Rational Test Control Panel
> Open Services for Lifecycle Collaboration - Automation WG joint chair
>
> E-mail: martinpain at uk.ibm.com
> Find me on: [image removed] and within IBM on: [image removed]
>
> [image removed]
>
>
>
>
>
> IBM United Kingdom Limited
> Registered in England and Wales with number 741598
> Registered office: PO Box 41, North Harbour, Portsmouth, Hants. PO6 3AU
>
>
>
> From: John Arwe <johnarwe at us.ibm.com>
> To: oslc-automation at open-services.net,
> Date: 13/03/2014 14:57
> Subject: Re: [Oslc-Automation] Changes I have made to Actions
> specs based on Actions issues list
> Sent by: "Oslc-Automation"
<oslc-automation-bounces at open-services.net>
>
>
>
> I'm saying:
>
> 1: When it is the case that the request has completely finished by
> the time the server sends its response, then it has a choice of status
codes:
>
> 1a: 200 is appropriate when the server has no intention of
> persisting the entity in the HTTP response; its response must be
> multityped as both AutomationRequest and AutomationResponse *and*
> entity's state must be "finished" (as defined by Auto 2.0) . Since
> (as far as the client can tell) nothing was created, the client has
> no subsequent responsibility to delete anything... and, indeed, it
> receives no URL from the server against which it would use in a
> subsequent DELETE request; it could attempt to use links in the
> response entity or a query, but there are enough "not Must"s in 2.0
> that it is not guaranteed to find such a URL if it did try.
>
> 1b: 201 is more appropriate in all other Automation-governed cases.
> The 201-Location's resource can be anything allowed by Automation,
> which includes but is not limited to case 1a.
>
> The 201 Automation-governed qualification is because I can see the
> *potential* to use AutomationRequest's in ways other than what the
> Automation spec defines, for example in a generic 202 response
> entity as we've discussed before. But that's outside Automation,
> hence outside the scope of this discussion.
>
> 2: We have concrete cases where 200 was anticipated [2], and where
> it was shown as a potential consequence of 2.0's content [1].
>
> 3: I am confirming that the concrete cases have in fact been
> implemented, and there is a deployed base of exploiting products
> currently in operation.
> Best Regards, John
>
> Voice US 845-435-9470 BluePages
> Tivoli OSLC Lead - Show me the Scenario
>
>
>
>
> From: Martin P Pain <martinpain at uk.ibm.com>
> To: John Arwe/Poughkeepsie/IBM at IBMUS,
> Cc: oslc-automation at open-services.net, "Oslc-Automation"
> <oslc-automation-bounces at open-services.net>
> Date: 03/13/2014 09:37 AM
> Subject: Re: [Oslc-Automation] Changes I have made to Actions
> specs based on Actions issues list
>
>
>
> So are you saying "We have concrete cases for 200 - but in those
> cases the action has completed, so there's no bug",
>
> or are you saying "We allow providers to return 200, but don't
> define in the spec what that means so it could mean anything, so the
> bug stands"
> Do we have any concrete cases for a 200 being returned when the
> Result has not been finished?
>
> or are you saying "We allow providers to return 200, and it's
> possible that that could mean it hasn't finished, but it's unlikely
> that that will happen (or that's base use of the HTTP return codes)
> so it's the provider's problem not the specs - so there's no bug"?
>
>
>
> Martin Pain
> Software Developer - Green Hat
> Rational Test Virtualization Server, Rational Test Control Panel
> Open Services for Lifecycle Collaboration - Automation WG joint chair
>
> E-mail: martinpain at uk.ibm.com
> Find me on: [image removed] and within IBM on: [image removed]
>
> [image removed]
>
>
>
>
>
>
>
> IBM United Kingdom Limited
> Registered in England and Wales with number 741598
> Registered office: PO Box 41, North Harbour, Portsmouth, Hants. PO6 3AU
>
>
>
> From: John Arwe <johnarwe at us.ibm.com>
> To: oslc-automation at open-services.net,
> Date: 13/03/2014 12:13
> Subject: Re: [Oslc-Automation] Changes I have made to Actions
> specs based on Actions issues list
> Sent by: "Oslc-Automation"
<oslc-automation-bounces at open-services.net>
>
>
>
> [in cheesy chop-socky movie style] What?!? You dare question the
> spec-fu master?!? [lips keep moving for another 5 seconds]
>
> Base Automation (2.0) allows producers to return a 200 in cases
> where they return a request+result and the result has already
> "finished" [3]. See [1], [2]; we have implementations using this
> since 2.0 - it's somewhat popular in operations actually, where the
> duration of the plan's execution varies widely based on parameters
> ... hitting one endpoint is quick, hitting 10K of them... less so.
>
> We oscillated wildly during 2.0 drafting on the subject of how
> "obvious" to make this case; it's really just an optimization of the
> "more traditional" 201/poll Automation flow, so we ended up being
> fairly low key about it. If you look at the wiki history for
> section [3] you'll see how it waxed and waned. One of the
> "optimizations" inherent in using 200 instead of 201 is that there
> is no need (with 200) for the provider to persist the request+result
> representation at all (although it's still free to); as far as the
> client is concerned (a) there is no need/perhaps ability to GET/poll
> for it (b) there is no need to DELETE it. So it saves at least 2
> HTTP flows over the normal case, with all that implies.
>
>
> [1] http://open-services.net/wiki/automation/OSLC-Automation-
> Version-2.0-Samples/#Example-2
> [2]
http://open-services.net/wiki/automation/Synchronous-Execution-Scenario/
> [3] http://open-services.net/wiki/automation/OSLC-Automation-
>
Specification-Version-2.0/#Asynchronous-and-Synchronous-Automation-Execution
> Best Regards, John
>
> Voice US 845-435-9470 BluePages
> Tivoli OSLC Lead - Show me the Scenario
>
> > > A FB-200 means "I did it"
> > > (past tense, otherwise it should be a 202). A AR-200 means "I
> > > created the AR, now you [consumer] monitor it until state/verdict
> > > say it's baked".
> >
> > I would expect AR factories to return a 201 Created response code.
> > Appendex A states:
> >
> > http://open-services.net/wiki/core/Exposing-arbitrary-actions-on-
> > RDF-resources/#constructing-http-requests
> > "201 (Created) to indicate that the request resulted in the creation
> > of a new resource; the Location response header provides the URL of
> > the newly created resource. The client is responsible for
> > interrogating the resource’s state to determine whether or not the
> > action has completed. One use of this in certain profiles is to use
the
> > OSLC Automation specification’s mechanisms to monitor its progress
> > and success/failure."
> >
> > So the only issue, as I see it, is if providers respond with a 200
> > when it has created an Auto Request, which I would consider to be
> > bad practice anyway (I haven't checked if the spec says what
> > response code it should use, but I woudn't be suprised if it doesn't
say).
> _______________________________________________
> Oslc-Automation mailing list
> Oslc-Automation at open-services.net
>
http://open-services.net/mailman/listinfo/oslc-automation_open-services.net
>
>
> Unless stated otherwise above:
> IBM United Kingdom Limited - Registered in England and Wales with
> number 741598.
> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU
> _______________________________________________
> Oslc-Automation mailing list
> Oslc-Automation at open-services.net
>
http://open-services.net/mailman/listinfo/oslc-automation_open-services.net
>
>
> Unless stated otherwise above:
> IBM United Kingdom Limited - Registered in England and Wales with
> number 741598.
> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU
> _______________________________________________
> Oslc-Automation mailing list
> Oslc-Automation at open-services.net
>
http://open-services.net/mailman/listinfo/oslc-automation_open-services.net
Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number
741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140314/a3ebc893/attachment-0003.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/jpeg
Size: 518 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140314/a3ebc893/attachment.jpe>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/jpeg
Size: 1208 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140314/a3ebc893/attachment-0001.jpe>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/gif
Size: 360 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140314/a3ebc893/attachment.gif>
More information about the Oslc-Automation
mailing list