Distributed Computing
**DRAFT**
Overview
Nowadays more and more web applications are being written to take advantage of remote services that offer access to remote data and other such services through the use of protocols built upon open standards such as HTTP and XML. They allow for easy interoperation between heterogeneous environments and are generally refered to as “web services”. Google and Amazon are two such examples of companies that offer such services. This document provides a brief overview of SOAP, a method of invoking remote procedures, and WSDL, a format that describes what procedures are offered by a remote service.
SOAP on the Wire
The Simple Object Access Protocol (SOAP) a remote procedure protocol that works over HTTP. For the purpose of this document SOAP messages are sent over the network embedded as HTTP POSTs. The payload of a SOAP message is specified as XML.
You may never have to look at the format of the messages that are sent across the wire but it helps to understand what is going on behind the scenes. The request, e.g. the procedure call, is wrapped in a <SOAP-ENV:Body> which in turn is contained within a <SOAP-ENV:Envelope> element. This is also true of any response.
The following examples show the raw SOAP request/response messages that are sent across the wire. In this particular case the remote procedure being invoked uses Amazon’s web service and allows the user to search for items in the Amazon database that match the given search criteria.
Request
POST /onca/soap?Service=AWSECommerceService HTTP/1.0
Host: soap.amazon.com
Content-Type: text/xml; charset=UTF-8
Content-Length: 723
SOAPAction: "http://soap.amazon.com"
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Body>
<ItemSearch xmlns="http://webservices.amazon.com/AWSECommerceService/2005-07-26">
<SubscriptionId xsi:type="xsd:string">XXXXXXXXXXX</SubscriptionId>
<Request>
<Keywords xsi:type="xsd:string">donald norman</Keywords>
<SearchIndex xsi:type="xsd:string">Books</SearchIndex>
</Request>
</ItemSearch>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Response (edited for conciseness)
HTTP/1.1 200 OK
Connection: close
Content-Type: text/xml; charset=UTF-8
<?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/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<ItemSearchResponse xmlns="http://webservices.amazon.com/AWSECommerceService/2005-07-26">
<Items>
<TotalResults>128</TotalResults>
<TotalPages>13</TotalPages>
<Item>
<ASIN>0465067107</ASIN>
<DetailPageURL>http://www.amazon.com/exec/obidos/redirect?....</DetailPageURL>
<ItemAttributes>
<Author>Donald A. Norman</Author>
<ProductGroup>Book</ProductGroup>
<Title>The Design of Everyday Things</Title>
</ItemAttributes>
</Item>
...
</Items>
</ItemSearchResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Describing Your Service
Once a service is up and running, people need to know what procedures are available. A Web Service Description Language (WSDL) file is a formal description of the callable functions that are available. It describes the API. Most web application toolkits for developing SOAP applications use the WSDL file to automatically generate proxy functions that can be called as if the service were running locally. The WSDL that describes Amazon’s service can be found here. View the page source to see the file.
To understand the format of the WSDL file, let’s look at the WSDL file that describes Amazon’s web service. As there are many procedures that can be invoked remotely we will focus on just one particular procedure, ItemSearch. This procedure accepts a number of parameters that allows the user to search through Amazon’s database for items that match the given search criteria. It is worth noting that the latest version of the WSDL specification is version 2.0. The Amazon WSDL file appears to conform to an earlier version of the spec.
We know that the Amazon service will be sending and receiving messages, so a good starting point is define the types of messages that the service will use. Message types are defined within the types element of a WSDL document.
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:tns="http://webservices.amazon.com/AWSECommerceService/2005-07-26"
targetNamespace="http://webservices.amazon.com/AWSECommerceService/2005-07-26">
<types>
<xs:element name="ItemSearch">
<xs:complexType>
<xs:sequence>
<xs:element name="SubscriptionId" type="xs:string" minOccurs="0"/>
<xs:element name="AssociateTag" type="xs:string" minOccurs="0"/>
<xs:element name="XMLEscaping" type="xs:string" minOccurs="0"/>
<xs:element name="Validate" type="xs:string" minOccurs="0"/>
<xs:element name="Shared" type="tns:ItemSearchRequest" minOccurs="0"/>
<xs:element name="Request" type="tns:ItemSearchRequest" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ItemSearchResponse">
<xs:complexType>
<xs:sequence>
<xs:element ref="tns:OperationRequest" minOccurs="0"/>
<xs:element ref="tns:Items" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</types>
Message types can be nested. For example the ItemSearch message type contains a field, Request, that is an ItemSearchRequest message type (description not included above). If you look at the example of a SOAP request defined earlier, the fields in the body of the request correspond to the fields defined in the message type. All the fields are not compulsory, only those that are required are actually used.
Once the message types have been defined, the message themselves have to be defined. The message element is used to define messages. For the ItemSearch procedure, there are two types of messages: ItemSearchRequestMsg and ItemSearchResponseMsg. They are defined as follows:
<message name="ItemSearchRequestMsg"> <part name="body" element="tns:ItemSearch"/> </message> <message name="ItemSearchResponseMsg"> <part name="body" element="tns:ItemSearchResponse"/> </message>
The procedures themselves, or operations, are then defined in terms of messages. The operation ItemSearch uses the ItemSearchRequestMsg and ItemSearchResponseMsg message types that were defined in the types section. The definition looks like this:
<operation name="ItemSearch"> <input message="tns:ItemSearchRequestMsg"/> <output message="tns:ItemSearchResponseMsg"/> </operation>
Both the input and output elements together describe the interaction between client and server. The WSDL specification calls these interactions “message patterns”. The ItemSearch operation uses the in-out pattern because the operation consists of a simple request-response interaction. The client sends a list of search parameters and the server responds with a list of results. There are other message patterns but this document does not describe them.
Finally, the service element of the WSDL file describes where to find the service. All requests must be sent to the URL specified by the location attribute of the soap:address element.
<service name="AWSECommerceService">
<port name="AWSECommerceServicePort" binding="tns:AWSECommerceServiceBinding">
<soap:address location="http://soap.amazon.com/onca/soap?Service=AWSECommerceService"/>
</port>
</service>
Conclusion
Using the steps outlined above it should now be possible for you to read a WSDL document. Unfortunately, in the case of Amazon, there doesn’t appear to be any other way of figuring what procedures are available and the parameters that they take other than by deciphering the WSDL file. A human friendly format would be much more useful, especially when you are trying to write code that uses the API.