The SOAP Protocol
If you know HTTP and XML, you'll learn SOAP in minutes. Essentially, SOAP defines how a client should format its request and how the server should format its answer.
This discussion is based on SOAP 1.1, the latest version at the time of writing. At the time of writing, SOAP is not formally an Internet standard, but it appears that W3C might define its own XML-based RPC protocol. This new protocol would be based on the same principle as SOAP but might differ in the details.
I will post articles and news as the status of SOAP clarifies at http://www.marchal.com.
Listing 9.1 is a SOAP request. As you can see, it's an HTTP 1.1 POST request with an XML payload. The SOAP specification mandates the use of HTTP 1.1, POST , and XML. It also mandates the presence of the Content-Length and SOAPAction headers in the request.
SOAPAction is specific to SOAP. It is loosely defined in the specification as a URI identifying the intent of the request. However, it need not be the URL of the Web server (indeed, if you read the header, the request is for localhost/ stockq , not http://www.psol.com/xmlns/stockq).
You should not worry too much about SOAPAction . It was introduced primarily to help firewalls separate SOAP traffic from regular Web requests .
Listing 9.1 A SOAP Request
POST /stockq HTTP/1.1 Host: localhost Content-Type: text/xml Content-Length: 422 SOAPAction: "http://www.psol.com/xmlns/stockq" <?xml version='1.0'?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <psol:getStock xmlns:psol='http://www.psol.com/xmlns/stockq' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <manufacturer>Playfield</manufacturer> <sku>101</sku> </psol:getStock> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
The RPC is encoded as an XML document. SOAP defines the SOAP-ENV:Envelope , SOAP-ENV:Body , and SOAP-ENV:Header elements (in the http://schemas.xmlsoap.org/soap/envelope/ namespace).
SOAP-ENV:Envelope must be the root of SOAP requests. SOAP-ENV:Envelope can contain a SOAP-ENV:Header and must contain a SOAP-ENV:Body . In Listing 9.1, the optional SOAP-ENV:Header is not present.
The SOAP-ENV:Header carries extensions to SOAP. Headers were introduced to manage transactions, payments, or authentication. So far, though, they are not used frequently.
The SOAP-ENV:Body contains the RPC data. The name of the RPC is encoded as an XML element: psol:getStock for the getStock RPC in Listing 9.1.
The parameters of the call are also encoded as elements. SOAP offers a default encoding for parameters, which Listing 9.1 uses. However, your application can use any encoding, provided it is declared in the SOAP-ENV:encodingStyle attribute. For example, SOAP for Java from IBM can encode parameters following the SOAP rules or XMI.
The SOAP encoding lists the parameters as XML elements whose names match the parameter names . In Listing 9.1, the two parameters are manufacturer and sku . Their values are Playfield and 101 .
SOAP provides a mechanism to signal the type of the parameters. The specification states that values are always encoded as strings. For example, the integer fifty-three is represented by the string 53 .
SOAP defines an optional attribute ( xsi:type ) that you would use as follows :
However, xsi:type is not required if the parameter supports only one type. In practice, you mainly use xsi:type for object parameters because, through inheritance and polymorphism, recognizing the actual parameter's type is not always easy.
When the server recognizes a SOAP request, it parses the payload and extracts the RPC name and its parameters. It executes the call and prepares a response, again as an XML document sent over HTTP.
Listing 9.2 is the response for the query in Listing 9.1. As you can see, it's a regular HTTP response with an XML payload.
Listing 9.2 The SOAP Response
HTTP/1.1 200 OK Content-Type: text/xml Content-Length: 555 <?xml version='1.0'?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <psol:getStockResponse xmlns:psol='http://www.psol.com/xmlns/stockq' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <stockq> <manufacturer>Playfield</manufacturer> <sku>101</sku> <available>true</available> <level>10</level> </stockq> </psol:getStockResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
You are now familiar with SOAP-ENV:Envelope and SOAP-ENV:Body . The body of the response is again an XML element, but the specification does not specify its name. It could be anything, even though the specification suggests you'd use the RPC name suffixed with Response ( psol:getStockResponse ).
The first element within the response is the return value (again, the specification does not enforce its name). In this example, the return value is a structure with four fields.
SOAP's rule to encode structures is that the names of the elements must match the names of the fields. So, in Listing 9.2, the four fields are manufacturer , sku , available , and level .
Although Listing 9.2 does not illustrate it, a response can include out parameters. They simply appear after the response element.
As you have seen, in most cases, the content of SOAP-ENV:Body is defined by the application. However, SOAP defines one special element to report errors: SOAP-ENV:Fault . SOAP-ENV:Fault is a structure with four fields, the first two of which are mandatory:
Listing 9.3 is a response with an error. Note that SOAP mandates the use of the HTTP 500 return code.
Listing 9.3 A SOAP Fault
HTTP/1.1 500 Internal Server Error Content-Type: text/xml Content-Length: 333 <?xml version='1.0'?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>SOAP-ENV:VersionMismatch</faultcode> <faultstring>Unknown SOAP version</faultstring> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope>