RE: [getf] Proposal for Web-friendly representation of RPC's in SOAP

Hi Noah,

I think I generally like where this is going. There are one or two places
where we could more uniformly 'expose' the intermediate messaging operation
between RPC and HTTP - you do do this in a couple of places, which I like...


Some commentary intertwined below.

Many thanks

Stuart
--
> -----Original Message-----
> From: noah_mendelsohn@us.ibm.com [mailto:noah_mendelsohn@us.ibm.com]
> Sent: 29 May 2002 15:05
> To: xml-dist-app@w3.org
> Subject: [getf] Proposal for Web-friendly representation of RPC's in
> SOAP
> 
> Note: this mail is intended primarily for members of the GETF task force,
> which is working on proposals for making SOAP more web-friendly. Others
are
> welcome to peek.
> 
> The main technical issue that we did not get to on last week's GETF call
> was the handling of RPC.   Here is the very rough outline of a proposal.
> Perhaps we can discuss this a bit on the call today.  My intention is to
> build on the work that we've already agreed regarding message pattern and
> the HTTP binding.   I hope we can discuss this on today's call.
> 
> 
> GOALS OF THIS RPC APPROACH
> 
> * Set out a direction that allows convenient bindings to traditional
> programming language method calls.
> 
> * Ensure that URI's are used to identify resources.

Minor gnit... I'd state it the other way round ie.

"Ensure that resources are identified by URI's"

> * Ensure that data representing updates to a resource is carried in the
> body of the SOAP message, not in the URI.
> 
> * Where only retrieval is to be performed, use GET.  Where resource
> creation or complete replacement is involved, use PUT.  Where partial
> updates or sub-resource creation is involved, use POST.

Ok... but I would like to see the mapping through messaging
operations/patterns and thence to HTTP methods.

> * That provide appropriate symmetry in the handling of SOAP
representations
> of:
> 
>       Integer getQuantityOnHand(String stockId)
>       setQuantityOnHand(String stockId, Integer newQuantity)
> 
> PROPOSAL
> 
> (None of this text is intended to be polished or final.  It is only to
> convey the idea.)
> 
> Update to the HTTP Binding
> 
> I suggest we add to the HTTP binding a binding-specific feature allowing
> applications to select between PUT and POST (and maybe DELETE as well)
when
> sending a request/response.  To do this we would introduce one new
property
> which the application would use to choose the verb.  This feature is used
> in the RPC description below.

The framework certainly allows us to do this through the introduction of
additional properties that affect and are affected by the operation of the
relevant FSMs. However, I do feel wary about exposing HTTP more directly to
the SOAP node. I like thinking in terms of 'what is the re-usable messaging
operation'.

I think the mapping of a "message-poll" (note poll, not pull) onto HTTP GET
(that retrieves a SOAP message) makes sense, and I can also conceive of a
"message-poll" in the context of bindings to other underlying protocols.

I could think of PUT as a "message-send" operation (one-way no response
message expected - not sure) - which could be distinguished with YAM
(Yet-Another-MEP). 

I guess the alternative to multiple MEP's is a single parameterised MEP (eg.
a mode to switch between poll, send, request-response). In many respects
that would be pretty much the same as you propose, but the emphasis is in
messaging operations rather than HTTP methods.

We probably also need to state that the "message-poll" operation (or
whatever we call it) is expected to be (required to be) 'safe'.

> Update to the RPC section
> 
> Somewhere in the general introduction to RPC state:
> 
> Use of RPC on the World Wide Web
> 
> The primary purpose of this RPC convention is to allow convenient binding
> of SOAP messages to method and procedure calls in commonly deployed
> programming languages.  The architecture of the World Wide Web requires
> that some care be observed in the proper use of SOAP RPC mechanisms.
> Specifically, well-written Web applications conform to the following
> conventions, among others:
> 
> * Resources are identified with URI's; it is inappropriate to use
> information conveyed in the body of the message to id the entify a
typo?                                                ^^^^^^^^^^^^^identity
of?

> resource.  The body of a message MAY carry such identifying information in
> a manner that is redundant with the URI (for example, it is not an error
to
> carry the URI of a resource in the message itself).
> 
> * When the operation be performed is to do a safe retrieval of information
> from the resource (I.e. a representation of the resource) safe methods
such
> as HTTP GET should be used.

...a "message poll" if we want to express this in a binding independent way?

> * When creating or completely replacing a resource using 
> HTTP, PUT should be used.

Hmmm... I get feeling of chameleon/messaging awkwardness coming through
here.

I feel that we have a layering of RPC ontop of messaging, so I am repeatedly
drawn to thinking of SOAP in terms of messaging operations, so I find myself
looking for the intermediate messaging abstraction (which in the HTTP case
would make use of PUT).

> * When partially updating the resource identified by a URI, or creating a
> sub resource, POST should be used.

Sort of ditto... update->RR->POST...

I'm broadly ok with what follows here...

> Some care must be taken in the use of SOAP RPC to ensure that these Web
> conventions are properly observed.  Consider, for example, a binding to
> SOAP of the following methods which in many programming languages would
> look similar to the following.  These methods are intended to query and
> update a database tracking the quantity available for certain parts in an
> inventory:
> 
>       Integer getQuantityOnHand(String partId)
>       setQuantityOnHand(String partId, Integer newQuantity)
> 
> In both methods, the partId represents a resource identification that
> should be carried in the URI, and the URI should be the same in both
cases.
> The method names "getQuantityOnHand" and "setQuantityOnHand" further
> identify the resource as being the quantity; such identification should
> also, ideally, be carried in the URI.  The newQuantity argument represents
> an update value and should not be carried in the URI.
> 
> Accordingly, the following conventions are established for the proper use
> of SOAP RPC on the World Wide Web, and with the message exchange patterns
> and HTTP binding proposed in this specification:
> 
> * The resource to be retrieved or updated SHOULD be identified by a URI.
> When mapping to or from a programming language method or procedure call,
> any arguments that serve to identify resources (such as partID above)
> SHOULD be represented in the URI to which the SOAP message is addressed.
> No standard means of doing such mapping is provided by this specification.
> 
> * When mapping to or from a programming language method or procedure call
> the name of which identifies or qualifies the identification of a resource
> (such as QuantityOnHand above), such naming or qualification SHOULD be
> represented in the URI to which the SOAP message is addressed.  No
standard
> means of doing such mapping is provided by this specification.
> 
> * Any method representing a side-effect-free retrieval of resource data
> SHOULD be effected using the resource naming conventions described
> immediately above, and using the one-way pull message exchange pattern
(see
> XXX).  When used with the HTTP binding provided by this specification, the
> result is an HTTP GET to the resource in question.  Using this convention,
> no SOAP Body child element is used to represent the RPC when doing such
> retrieval.

I like this articulation (the last paragraph above) because it does
explicitly factor in the intermediate message view.

> * Methods representing creation or update of a resource are represented as
> SOAP bodies in the format described in this chapter.   Arguments
> representing data SHOULD be carried in the SOAP body (I.e. as the argument
> struct or array described in section XXX).  Arguments identifying the
> resource MAY be carried, but should in all cases be redundant with
> information available in the URI.

Just a question, but if we think of the email/smtp binding, do we imagine
following suit here with mailto: URIs

eg. mailto:part1234/quantityinhand@example.org or
    mailto:quantityinhand@example.org?subject=part1234 or...

> * When performing a resource creation the method name carried as the
> immediate child of the SOAP body element is interpreted as the name of a
> constructor.  In other words, the method name describes the means by which
> the arguments are used to create the resource.  When using the HTTP
binding
> provided by this specification, resource creation should be performed
using
> the HTTP PUT operation.

Would like to see the messaging step exposed as well. Also, not sure (either
way) about whether we need to distinguish constructors from other methods.
With PUT one feels that the 'slot' for the resource already exists (by
'magic') and that what is being PUT is a complete resource representation. 

> * When doing a partial update or creating a sub resource, the method name
> carried in the SOAP body conveys the nature of the update to be performed,
> and the interpretation of the arguments.  When using the HTTP binding
> provided by this specification, partial updates and/or sub-resource
> creation should be performed using the HTTP POST operation.

ditto on "Would like to see the messaging step exposed as well."

> * Methods MAY be designed to perform more effectively on the World Wide
Web
> by providing for them to return URI's representing many newly created
> resources or sub resources.  Implementations using the HTTP binding of
this
> specification MAY further provide for setting the HTTP response
> content-location header in such circumstances;

> no standard means for setting the pattern is provided.

Not sure what this last clause means - we do provide for the MEP in
operation to be identified in the message exchange context. Indeed, the RPC
description could hook-in to using these message exchange contexts... so
that the RPC conventions will likely make use of multiple MEPs.

> Similarly, implementations of nodes
> invoking RPCs MAY provide for application access to the value of
> content-location headers returned with responses;  no standard means for
> providing such access is provided.

Hmmmm.... I think that we almost have that already, see the descriptions of
"reqres:ImmediateSender" in part 2 and the setting of this value in the HTTP
binding descriptions.

> NOTE:
> In general, this specification concerns itself with the creation and
> processing of SOAP envelopes, and does not formally constrain the means by
> which RPC or non-RPC URIs are constructed for use with SOAP.  Thus, no
> standard means of mapping resource-identifying arguments or method names
to
> URIs is provided herein; it is anticipated that such conventions would be
> developed in conjunction with the creation of Web service description
> languages, language bindings, and so on.
> 
> ------------------------------------------------------------------
> Noah Mendelsohn                              Voice: 1-617-693-4036
> IBM Corporation                                Fax: 1-617-693-8676
> One Rogers Street
> Cambridge, MA 02142
> ------------------------------------------------------------------

Received on Wednesday, 29 May 2002 17:21:59 UTC