URI/RPC Primer Changes

The Primer implies that using URIs correctly is only important in an RPC
context. But the truth is that *whenever* SOAP is used over HTTP, the
SOAP specification recommends that the URI should be
resource-identifing. The primer also has a confusing paragraph-ordering
in that it concentrates on resource retrievals and then switches to
mentioning POST later. Reading the beginning of the section you would
never expect what comes at the end.

=====
I propose to change the title:

 change: 3.1.3 Conveying Web-friendly RPCs
 to: 3.1.3 Web-friendly SOAP Messages

Then I propose to add at the very beginning:

 add: "One of the most central concepts of the World Wide Web is that of
a URI as a resource identifier. SOAP services that use the HTTP binding
and wish to interoperate with other Web software should use URIs to
address all important resources in their service."

Then I propose to start the next paragraph with the phrase "For
example," 

 change: A very important - indeed predominant - use ...
 to: "For example, a very important - indeed predominant - use of the
World Wide Web is pure information retrieval, "

Next I propose to remove references of the word "RPC" to indicate that
the points made are more general than RPC:

 change: There are many instances when RPCs are designed ....
 to: There are many instances when messages are designed ....

 change: with a parameter of the RPC representing the object .....
 to: with an element of the body representing the object ....

I do not believe that the word "typical" should be used to describe the
historical SOAP/RPC behaviour. Hopefully in a year what is typical will
have changed.

 change: In the typical SOAP/RPC usage scenario, the HTTP ...
 to: In some SOAP/RPC implementations, the HTTP ....

More removals of the over-specific "RPC":

 change: Even in this case, the HTTP POST with a SOAP message conveying
the RPC can be represented in a Web-friendly manner. 
 to: Even in this case, the HTTP POST with a SOAP message can be
represented in a Web-friendly manner. 

 change: As with the use of the GET, Part 2 recommends that any part of
the RPC signature that serves
 to: As with the use of GET, any part of the message that serves

 change: The same parameters may, of course, be retained in the encoded
RPC in the SOAP Body element.
 to: The same parameters may, of course be retained in the SOAP Body.

 change: Note, however, that the all the parameters in the RPC signature
....
 to: Note, however that all of the resource-identifying elements have
been retained

-- 
Come discuss XML and REST web services at:
  Open Source Conference: July 22-26, 2002, conferences.oreillynet.com
  Extreme Markup: Aug 4-9, 2002,  www.extrememarkup.com/extreme/

Received on Thursday, 18 July 2002 16:45:55 UTC