Resolution for PR issue 430

Hello Zvi:
You raised an issue[1], which we have classified as PR issue#430 [2], which 
is a text/example disagreement involving examples 9 and 13 in the SOAP 
Primer [3]. Thank you for noting this discrepancy. The WG has resolved this
with the following amendments to the Primer.

1. In example 9, replace the first line with:
POST /Reservations HTTP/1.1

2. Rewrite the 1st para following example 9 (>>deletions<<, <<additions>>) thus:

"Example 9 shows an RPC request directed at >>a specific reservation at<< the travel 
service application. The SOAP message is sent in the body of a HTTP POST method 
directed at the URI identifying the >>specific reservation<< <<"Reservations" resource
on the server travelcompany.example.org>>. When using HTTP, the request URI indicates 
the resource to which the invocation is "posted". Other than <<requiring that>> it be a 
valid URI, SOAP places no formal restriction on the form of the request URI (see [RFC 2396] 
for more information on URIs). However, one of the principles of the Web architecture is 
that all important resources be identified by URIs. This implies that most well-architected 
SOAP services will be embodied as a large number of resources, each with its own URI. Indeed, 
many such resources are likely to be created dynamically during the operation of a service, 
such as, for instance, the specific travel reservation shown in the example. So, a 
well-architected travel service application >>will<< <<should>> have different 
URIs for each reservation, and SOAP requests to retrieve or manipulate those reservations 
will be directed at their URIs, and not at a single monolithic "reservations" URI, <<as
shown in Example 9>>.<< Example 13 in section 4.1.3 shows the preferred way to address
resources such as a particular travel reservation. Therefore, we defer until section 4.1.3 
further discussion of Web architecture compatible SOAP/HTTP usage.>>"

3. Delete the 2nd para following Example 9 (it will be moved and merged into section 4.1.3, 
see item 5 below).

4. Rewrite the 1st para **before** Example 13 (>>deletions<<, <<additions>>) thus:

"Example 13 is the same as that in Example 9, except that the <<HTTP>> Request-URI has been 
modified to include the reservation code, which serves to identify the resource (the reservation 
in question, which is being confirmed and paid for) >>, while the other parameters in the RPC, 
such as the creditCard number are ancillary data to be processed by the resource. Note, however, 
that all the resource-identifying elements have been retained as in Example 9 in their encoded 
form in the SOAP env:Body element<< . 

5. Add a **new** paragraph just **after** Example 13 with the following text (modified deleted text 
from item 3 above):

"In Example 13, the resource to be manipulated is identified by two things: the first is that it 
is a reservation (part of the method name), and the second is the specific instance of a reservation 
(which is the value of the parameter code to the method). The remainder of the parameters in the RPC 
such as the creditCard number are not resource-identifying, but are ancillary data to be processed 
by the resource. It is the recommendation of [SOAP Part2] that resources that may be accessed by 
SOAP-based RPCs should, where practical, place any such resource-identifying information as a part 
of the URI identifying the target of the RPC. It should be noted, however, that [SOAP Part2] does 
not offer any algorithm to do so. Such algorithms may be developed in future. Note, however, that 
all the resource-identifying elements have been retained as in Example 9 in their encoded form in 
the SOAP env:Body element."

These changes can be seen in the latest editor's copy of the Primer, available at [4].

Please let the WG know via xmlp-comments@w3.org if you are not satisfied with this proposal.

Thank you,
Nilo Mitra
editor, SOAP Primer
on behalf of the XMLP WG

[1] http://lists.w3.org/Archives/Public/xmlp-comments/2003May/0009.html
[2] http://www.w3.org/2000/xp/Group/xmlp-pr-issues.html#x430
[3] http://www.w3.org/TR/2003/PR-soap12-part0-20030507/
[4] http://www.w3.org/2000/xp/Group/2/06/LC/soap12-part0.html




Nilo Mitra
Ericsson, Inc.
phone: + 1 212 843 8451
mobile: +1 516 476 7427
nilo.mitra@ericsson.com

Received on Tuesday, 3 June 2003 17:53:33 UTC