Friday, October 26, 2007

Dave Winer on SOAP, REST and XML-RPC.

A good link http://www.kbcafe.com/rss/?guid=20060704042846

Note: Reproduced from site

SOAP Request

GET /stock HTTP/1.1
Host: www.kbcafe.com


<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
xmlns:m="http://www.kbcafe.com/stock">
<soap:Header>
<m:DeveloperKey>1234</t>
</soap:Header>
<soap:Body>

<m:GetStockPrice>
<m:StockName>HUMC</m:StockName>
</m:GetStockPrice>
</soap:Body>
</soap:Envelope>

The SOAP request tends to be overly verbose, but generally (not always) easy to understand. The SOAP envelope wraps an optional Header and the Body. The Body contains the actual XML request object. The Header contains information not required to service the request, but that help in some other way. A common use of the SOAP Header is the attachment of user credentials to the request. The beauty of SOAP is that it's not bound to the HTTP transport, although HTTP is by far the most commonly used transport for SOAP messages.



SOAP Response

HTTP/1.1 200 OK

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
xmlns:m="http://www.kbcafe.com/stock">
<soap:Body>
<m:GetStockPriceResponse>
<m:Price>27.66</m:Price>

</m:GetStockPriceResponse>
</soap:Body>
</soap:Envelope>

The SOAP response, also slightly overly verbose, but easy to understand. Now, imagine getting this response and you want the m:Price element text. How would you formulate the XPath to acquire this bit of information? Very simple ("//m:Price/text()").


REST Request

GET /stock?StockName=HUMC HTTP/1.1
Host: www.kbcafe.com

The beauty of REST is that GET requests do not require a request package. In this case, the parameter data is simply passed as an HTTP request parameter. Of course, this simplicity comes with a price. You are now bound to the HTTP protocol. Although the argument has been made that the principles of REST are not bound to HTTP, nobody has ever documented that approach.


It's important I explain here that REST is primarily used to service GET requests. By GET, I mean REST requests using the HTTP GET verb. REST uses three other HTTP verbs POST, PUT and DELETE. GET is used to retrieve data, POST to create, PUT to edit and DELETE to ... umh... delete. The HTTP verb is another element that binds the REST protocol to HTTP.


REST Response

HTTP/1.1 200 OK


<?xml version="1.0"?>
<m:Price xmlns:m="http://www.kbcafe.com/stock">27.66</m:Price>

The REST response is often very similar to the contents of the SOAP request body. And it's very easy to express an XPath and retrieve the data ("//m:Price/text()"). Note the REST response is actually simpler than the SOAP Body. This is by convention. SOAP transactions typically contain an element named with the method name and the strings Request and Response appended. This is actually unnecessary, but does have one advantage. REST request typically embed the method name within the request URL, which again binds the protocol to HTTP, whereas embedding the method name within the package allows SOAP to exist over any protocol.


XML-RPC Request

POST /stock HTTP/1.1
Host: www.kbcafe.com

<?xml version="1.0"?>
<methodCall>
<methodName>stock.GetStockPrice</methodName>

<params>
<param>
<value><string>HUMC</string></value>
</param>
</params>

</methodCall>

The XML-RPC request is the most verbose of all the protocols. This verbosity is what makes XML-RPC both difficult to use and lacking in inter-op. For example, the <string> element is optional, so the <value> element could have been expressed as <value>HUMC</value>. Several MetaWeblogAPI (the most common implementation of XML-RPC) providers assume the <string> element is present, while others assume it's not present. Whichever way you code it, at least one MetaWeblogAPI provider will fail. This leads to a lot of frustration for developers trying to write XML-RPC applications. You often have to code the request differently to compensate for different server implementations.



XML-RPC Response

HTTP/1.1 200 OK

<?xml version="1.0"?>
<methodCall>
<methodName>stock.GetStockPrice</methodName>
<params>
<param>

<value><double>27.66</double></value>
</param>
</params>
</methodCall>

Again, the XML-RPC response is the most verbose and again it contains a gross limitation. What's the XPath for retrieving the data? If you said ("//double/text()"), then we might have a problem down the road. Imagine the provider augments his response with new elements that includes the stocks 365-day high and 365-day low. The XPath would fail. Neither SOAP or REST have this problem, because the elements are named semantically.