Section VII.5. REST Versus SOAP | Dynamic HTML: The Definitive Reference

VII.5. REST Versus SOAP

The XMLHttpRequest object is capable of interacting with Representational State Transfer (REST) and Simple Object Access Protocol (SOAP), each of which has its zealots. Typically, details of a REST server request are appended to the end of a URL as a search string, and the GET method is used for the transfer. In contrast, SOAP calls are POSTed to the server, and the details must be sent in a string consisting of a well-formed XML document (i.e., not a document node object). Your decision about which way to go with the XMLHttpRequest object is determined solely by which approach the server uses.

Examples shown earlier are suitable for REST requests. If some of the data submitted to the server comes from form controls modified by users, your script can assemble the search string by reading the form control names and value, formatting them in the name1=value1&name2=value2&etc. style, and then appending that group to the URL (placing a ? symbol between the address and search string).

A SOAP submission is called a message. Its basic job is to convey one or more commands, each with zero or more parameters to the server. The message is formatted as XML and conforms to a structure that resembles the following pseudo-code:

 <Envelope>     <Body>         <command>             <parameter>value</parameter>             <parameter>value</parameter>         </command>     </Body> </Envelope>

To demonstrate how to make a SOAP call with XMLHttpRequest, I'll assume that the server delivering the HTML page also has a SOAP service that returns the up-to-the-minute currency conversion rates between two countries. This would allow a client-side script to perform the conversions locally within a single web page. A SOAP message to this service might look like the following:

 <SOAP-ENV:Envelope     xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"     xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"     xmlns:xsd="http://www.w3.org/1999/XMLSchema">     <SOAP-ENV:Body>         <ns1:getCurrencyRate             xmlns:ns1="urn:xmethods-CurrencyRate"             SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">             <countryfrom xsi:type="xsd:string">estonia</countryfrom>             <countryto xsi:type="xsd:string">australia</countryto>         </ns1:getCurrencyRate>     </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Only two small segments of this messagethe text nodes inside the countryfrom and countryto elementsvary from one submission to the next. Therefore, your client-side script need only insert those user-supplied chunks of data (perhaps as values of select elements) into an otherwise hard-coded data string.

The following function receives two parameters for the desired country names, assembles the data as a long string (which wraps in the display below), and then passes execution to another function that sends the data via the XMLHttpRequest object. Parameters variables are highlighted to show where they are used within the function.

 function fetchConversionRate(fromCountry, toCountry) {     var url = 'http://example.com/soap';     var data = '<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP- ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/ XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"><SOAP-ENV:Body><ns1: getCurrencyRate xmlns:ns1="urn:xmethods-CurrencyExchange" SOAP-ENV: encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><countryfrom xsi:type="xsd: string">' + fromCountry + '</countryfrom><countryto xsi:type="xsd:string">' + toCountry + '</countryto></ns1:getCurrencyRate ></SOAP-ENV:Body></SOAP-ENV:Envelope> ';     loadSOAP(url, data, recalc); }

To send the message to the server, the XMLHttpRequest code differs slightly from the REST examples shown earlier (shown here in a procedural version, analogous to Example IV-10). The open( ) method specifies the POST method, and two setRequestHeader( ) methods prepare the headers. Finally, the send( ) method includes the XML-as-text data as its parameter, as shown in the following function.

 var soapReq; function loadSOAP(url, data, loadHandler) {     // native object only for demonstration     soapReq = new XMLHttpRequest( );     soapReq.open("POST", url);     soapReq.onreadystatechange = loadHandler;     soapReq.setRequestHeader("Content-Type","text/xml; charset=utf-8");     soapReq.setRequestHeader("SOAPAction","");     soapReq.send(data); }

You also have the option of assembling posted data as an XML document, out of the user's view. For example, if you use XMLHttpRequest to obtain a template for submission (such as the currency conversion SOAP command shown above), you could use DOM parsing to insert the text field values into that unseen XML document. You may then pass that completed XML document as the data parameter of the request object's send( ) methoda request object automatically serializes an XML document (i.e., converts it to a string) prior to sending.

After the data returns from the server, you can access it via the same responseXML or responseText properties of the instance of the request object described earlier.