[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.

* 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.

* 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.

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
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.

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

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

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.

* 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.

* 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.

* 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.

* 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.  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.

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 10:22:48 UTC