How SOAP Works

A SOAP request will involve creating and populating a request envelope, which contains all the required information (as specified by the WSDL document), transmitting that envelope to the API server, and handling the response.

A SOAP request generally contains all of the following elements:

• SOAP Envelope — With namespace inclusions.

• SOAP Body — Possibly defining additional namespaces.

• Desired Action — How the desired action is represented will depend on the API in question. It may be as simple as a parameter, or involve additional namespaces.

• Developer Key — A unique identifier assigned by the server to the requestor.

• Request Parameters — Detailing the request being performed.

With that information in mind, a SOAP request can be generated.

<?xmlversion="1.0" encoding=" UTF-8" standalone="no"?>
<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>
<devkey xsi:type="xsd:int">123</devkey>
<action xsi:type="xsd:string">search</action>
<type xsi:type="xsd:string">book</type>
<keyword xsi:type="xsd:string">style</keyword>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The parameters included in the request are easy to pick out, and though the variable typing isn't of great importance for PHP development, it does come in handy for more strongly typed languages. The missing item here is the endpoint, made clear in the REST example because it was the URL to which the request was posted. SOAP requests, of course, are run against specified URIs, which do not need to be re-specified within the request itself.

The SOAP response would look like this:

<?xmlversion='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>
<LibrarySearchResponsexmlns="http://library.example.com/api/ns">
<RequestInfo>
<devkey xsi:type=" xsd:string">123</devkey>
<action xsi:type="xsd:string">search</action>
<type xsi:type="xsd:string">book</type>
<keyword xsi:type="xsd:string">style</keyword>
</RequestInfo>
<ResponseInfo>
<ResultCount>2</ResultCount>
<Item>
<Title xsi:type="xsd:string">Style Book Vol 1</Title>
<Status xsi:type="xsd:string">Out</Status>
<Holds xsi:type="xsd:int">3</Holds>
<CopiesOnHand xsi:type="xsd:int">2</CopiesOnHand>
<Author xsi:type="xsd:string">Jon Doe</Author>
</Item>
<Item>
<Title xsi:type="xsd:string">Style Book Vol 2</Title>
<Status xsi:type="xsd:string">In</Status>
<Holds xsi:type="xsd:int">0</Holds>
<CopiesOnHand xsi:type="xsd:int">1</CopiesOnHand>
<Author xsi:type="xsd:string">Jon Doe</Author>
</Item>
</ResponseInfo>
</LibrarySearchResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The SOAP response isn't too different from the REST response shown earlier. In fact, much of the name spacing could actually be omitted (though it is rare to see a SOAP response without it), at which point, with the exception of the additional encapsulation, the two documents would be very similar.

As you should be able to discern from the response shown, it declares itself to be XML 1.0 and uses UTF-8 for encoding. The SOAP-ENV:Envelope element is the root element for the document, and has threenamespaces, including the SOAP-ENV namespace. The Body then contains the LibrarySearchResponse element among other things, which also defines its own namespace.

The RequestInfo parent follows after, and this contains the request parameters that generated the response that follows on from there. Returning request parameters with the response is a common occurrence in SOAP.

Finally, the response itself is returned. Notice that the ResultCount element sits as a direct child of ResponseInfo, and the result items themselves are again stored under a repeating element, Item.