Dave Winer on SOAP, REST and XML-RPC.
Scanning Greg Reinacker's latest roadmap for NewsGator, they support SOAP and REST, which I know from lots of experience means I have to work real hard just to try their stuff out. Too hard. Amazon's S3 service took this approach and their uptake is too slow, there's no visible momentum (I know I'll get lots of links for saying that). Go to a developer event, no one is talking about S3. That's terrible because it's a good idea and it deserves attention. I wonder why they are so cheap with the interfaces. Get over your religion Greg, and support XML-RPC, I bet it makes a difference. I won't dig into your stuff unless you do. Too much work for me, and I don't think you're going to get the uptake.
Dave believes that XML-RPC is easy compared to SOAP and REST. Let's examine the merits of each with concrete examples. Following is sample SOAP, REST and XML-RPC request and response messages. Note that I've left out some HTTP headers.
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.
But, there's one other issue that I think is extremely important. What happens when you type SOAP, REST and XML-RPC at Google? Most developers don't know the details of these protocols and are gonna need help. Let's try it. A search for SOAP on Google gives an array of great websites describing the protocol in both simple and detailed form. A search for REST on Google also gives a slightly smaller array of great websites describing the protocol, but none are authoritative. A search for XML-RPC on Google gives a smaller array of low quality websites describing the protocol. Yes, the websites describing XML-RPC are rot with 404 links and unmaintained webpages. The homepage at xmlrpc.com hasn't been updated in 3 years. Have you tried the XML-RPC validator? The top two news items on the news webpage points to 404 pages and the news webpage itself hasn't been updated in 4 1/2 years. Two of the last three questions on the mailing list remain unanswered after several weeks.
Anyhow, I tried not to express opinion in this short article, but that proved quite difficult. I hope you like it.
