RE: SOAP Web Method Feature, interface operation & HTTP binding (issues 54 & 64)

I like this addition of PUT and DELETE and support it.

I think the idea of expressing the "rest" operation in the interface may
be useful.  This is notion of "dual names" I list as options 5 and 6 in
my recent blog entry -
http://www.pacificspirit.com/blog/2004/04/13/operation_names_in_wsdl_cho
ices_choices_choices

The motivation for expressing the web method I describe as 
"It should be noted that the use of generic versus custom operations is
not mutually exclusive. One could easily see a scenario where an
application wanted a variety of "GET" methods, but also needs to
indicate that they are all follow the "GET" semantics of REST. One could
argue that the "binding" should take care of this, but having the 2
operation names on a given operation means that they can be re-used for
either multiple bindings to a given protocol or for use with protocols
that do not have generic interfaces. "

I think there are some other important points to think about.

Firstly, on naming, I'm uncomfortable with the use of the term "web
method" when describing a generic (REST) operation.  WSDL uses the term
"name" within an operation for specifying the name of the operation.
Thus I prefer "name" to "method".  Further, the notion of "web" has too
specific a meaning for me as it has a couple of different connotations.
For example, is it only for HTTP operations?  That is, if I bind a
web-method of "put" to IIOP, does it really make sense to call it a
"web" method?  In which case it really is just a binding issue.
Further, the Web is really defined to be about a network of resources
identified by URIs.  If my binding doesn't use URIs, then using the term
"web" method again doesn't make sense.  The abstraction that I think is
important is that the "method" is a constrained interface.  Hence why I
call it "restName".   Also, because the use of the "web method" aka
"REST name" is applicable to the non SOAP HTTP binding, I prefer
decoupling from the soap 1.2 term. 

The way I look at it, the interesting idea is that an operation actually
has 2 names, rather than just one.  It might be more accurate to
describe them as "customName" and "constrainedName", but that seems
cumbersome.  And I'd rather predispose things to treat the current use
of name as the 80/20 point, that is the simplest.  To me, the idea is
that this makes the simple thing (having 1 name) the simplest, and makes
the hard thing possible.

Now I'm prepared to live with calling this a "web method" because of the
way that soap 1.2 treats this.  And I can CERTAINLY live with it if it
turns out we spend a whole bunch of time arguing about the name....

Secondly, I'd like to think of a way of using that web method/rest name
in the binding.  Strawman: the http:binding could have an attribute for
re-using the webMethod, ie UseWebMethodAsHTTPOperations="true"...

Thirdly, I think there is a binding issue about binding abstract web
methods to different HTTP verbs.  Some corner cases: Atom's binding of
PUT and DELETE to HTTP POST, and binding of GET to POST for containing
Query bodies, aka XQueries.

Cheers,
Dave

> -----Original Message-----
> From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org]On
> Behalf Of Hugo Haas
> Sent: Wednesday, April 14, 2004 8:34 AM
> To: www-ws-desc@w3.org
> Subject: SOAP Web Method Feature, interface operation & HTTP binding
> (issues 54 & 64)
> 
> 
> We discussed issues 64[1] and 54[2] around the HTTP binding last week.
> 
> In the process of discussing issue 64, Dave and Yaron expressed that
> it would be interesting to be able to specify that a particular,
> RESTful, operation corresponds to a specific HTTP method (I believe
> that this corresponds to option #2 in Dave's email[5]).
> 
> This email goes over the solution I proposed on last week's call. It
> also proposed a simple addendum to the HTTP binding to address issue
> 54 at the end of the email.
> 
> Jonathan has shown[3] that it was possible to represent at the
> operation level an HTTP exchange. I believe that issue 64 mainly
> revolves around the syntax for such a description.
> 
> However, what is currently missing at the abstract level when one
> describes such an interface operation, is its mapping to a REST
> operation. I believe that we could reuse the SOAP Web Method Feature
> defined in SOAP Version 1.2: Part 2[4], which isn't SOAP-specific, at
> a low cost.
> 
> While defined in the SOAP specification and having "SOAP" in its name,
> this feature is abstract and only tied to SOAP by two MEPs defined in
> the SOAP specification: the SOAP Request-Response Message Exchange
> Pattern and SOAP Response Message Exchange Pattern. I believe that it
> could be used in WSDL 2.0, to characterize interface operations which
> use the In-Only, Robust In-Only, and In-Out MEPs.
> 
> The following text in Part 1, inspired of the text found in SOAP 1.2
> Part 2, would cover this:
> 
>   2.4.5 Web method characterization
> 
>   Protocols designed for use on the World Wide Web provide for
>   manipulation of resources using a small set of Web methods such as
>   GET, PUT, POST, and DELETE. These methods are formally defined in
>   the HTTP specification [RFC 2616], but other underlying protocols
>   might also support them.
> 
>   The SOAP Web Method Feature defined in SOAP Version 1.2 Part 2:
>   Adjuncts[link] MAY be used inside an interface operation component
>   to indicate that this operation has the semantics of a particular
>   Web method, indicated by the
>   http://www.w3.org/2003/05/soap/features/web-method/Method property
>   value. The SOAP Web Method Feature MAY only be used on operations
>   whose message exchange pattern is In-Only, Robust In-Only, or In-Out
>   as defined in WSDL 2.0 Part 2.
> 
>   [ NOTE: the following paragraph may be better suited for the binding
>   operation section. ]
>   When binding an interface operation using the SOAP Web Method
>   Feature with a binding specification supporting this feature, the
>   value of the
>   http://www.w3.org/2003/05/soap/features/web-method/Method property
>   SHOULD be taken into account.
> 
>   It is worth noting that using the SOAP Web Method Feature at the
>   interface operation level does not necessarily require the operation
>   to be bound to SOAP with the SOAP binding.
> 
> We also need to add the following in the HTTP binding specification,
> after table 3-1, to have the HTTP binding know about the SOAP Web
> Method Feature:
> 
>   The HTTP binding defined in this section supports the Web method
>   characterization as defined in WSDL 2.0 Part 1[link]. When the SOAP
>   Web Method Feature is used in the interface operation bound, the
>   value of the
>   http://www.w3.org/2003/05/soap/features/web-method/Method property
>   corresponds to the following methods, depending on the operation
>   style:
> 
>     http://.../web-method/Method 	Operation	Method
>     Property				Style
>     ---------------------------------  	---------------	
> ----------------
>     "GET"				URI style	"get"
>     "POST"				Multipart style	"form-data-post"
>     "POST"				any		"post"
>     "PUT"				any		"put"
>     "DELETE"				URI style	"delete"
> 
> With the text above, I believe that we will be able to adequately
> address Dave's #2 scenario. However, and we're getting to issue 54
> here, the text above mentions a "put" and a "delete" method for the
> HTTP binding which haven't been defined yet.
> 
> I believe that it would be simple to support PUT and DELETE can be
> done by adding two lines to Table 3-1. in Part 3, with the following
> data:
> 
>   PUT
>     Method: "put"
>     Input serialization: application/xml
>     Output serialization: application/xml
>     HTTP Method: HTTP PUT
>     Message Patterns: In-Only, Robust In-Only, In-Out
>     Operation style: any
> 
>   DELETE
>     Method: "delete"
>     Input serialization: application/x-www-form-urlencoded
>     Output serialization: application/xml
>     HTTP Method: HTTP DELETE
>     Message Patterns: In-Only, Robust In-Only, In-Out
>     Operation style: URI style
> 
> Note that issue 54 is about the support of all the HTTP methods, and
> this proposal doesn't talk about OPTIONS, HEAD, TRACE nor CONNECT. I
> don't think that OPTIONS, TRACE or CONNECT are needed, though somebody
> may object. Regarding HEAD, if we do need it (which I don't think we
> don't), it basically is "get" without support for In-Out.
> 
> Regards,
> 
> Hugo
> 
>   1. http://www.w3.org/2002/ws/desc/2/06/issues.html#x64
>   2. http://www.w3.org/2002/ws/desc/2/06/issues.html#x54
>   3. http://lists.w3.org/Archives/Public/www-ws-desc/2004Apr/0003.html
>   4. 
http://www.w3.org/TR/2003/REC-soap12-part2-20030624/#WebMethodFeature
  5. http://lists.w3.org/Archives/Public/www-ws-desc/2004Apr/0004.html
-- 
Hugo Haas - W3C
mailto:hugo@w3.org - http://www.w3.org/People/Hugo/

Received on Wednesday, 14 April 2004 14:46:53 UTC