SOAP
Simple Object Access Protocol
Use SOAP when you need a strict, standardized protocol for exchanging structured information in enterprise-level applications. It's known for its strong typing and security features.
Simple Object Access Protocol (SOAP) is a lightweight XML-based protocol that is used for the exchange of information in decentralized, distributed application environments. You can transmit SOAP messages in any way that the applications require, as long as both the client and the server use the same method. The current specification describes only a single transport protocol binding, which is HTTP.
SOAP perfectly fits into the world of Internet applications and promises to improve Internet interoperability for application services in the future. In essence, SOAP packages method calls into XML strings and delivers them to component instances through HTTP.
SOAP XML documents are structured around root elements, child elements with values, and other specifications. First an XML document containing a request (a method to be invoked and the parameters) is sent out. The server responds with a corresponding XML document that contains the results.
SOAP is not based on Microsoft technology. It is an open standard drafted by UserLand, Ariba, Commerce One, Compaq, Developmentor, HP, IBM, IONA, Lotus, Microsoft, and SAP. SOAP 1.1 was presented to the W3C in May 2000 as an official Internet standard. Microsoft is one of the greatest advocates of SOAP and has incorporated SOAP as a standard interface in the .NET architecture.
A SOAP stack, an implementation of the SOAP standard on the client side, is comprised of libraries and classes that offer helper functions. A significant Web service testing challenge is that there are a number of SOAP stack implementations that are not compatible with one another. So although SOAP is intended to be both platform- and technology-independent, it is not. Web services written in .NET are however always compatible with .NET clients—they use the same SOAP stack, or library. When testing a .NET Web service however, you need to confirm if the service is compatible with other SOAP stack implementations, for example, Java SOAP stack, to avoid interoperability issues.
SOAP client requests are encapsulated within HTTP POST or M-POST packages. The following example is taken from the Internet draft specification.
Sample Call
The first four lines of code are standard HTTP. POST is the HTTP verb which is required for all HTTP messages. The Content-Type and Content-Length fields are required for all HTTP messages that contain payloads. The content-type text/xml indicates that the payload is an XML message to the server or a firewall capable of scanning application headers.
The additional HTTP header SOAPAction is mandatory for HTTP based SOAP messages, and you can use it to indicate the intent of a SOAP HTTP request. The value is a URI that identifies the intent. The content of a SOAPAction header field can be used by servers, for example firewalls, to appropriately filter SOAP request messages in HTTP. An empty string ("") as the header-field value indicates that the intent of the SOAP message is provided by the HTTP Request-URI. No value means that there is no indication on the intent of the message.
The XML code is straightforward. The elements Envelope and Body offer a generic payload-packaging mechanism. The element GetLastTradePrice contains an element called symbol, which contains a stock-ticker symbol. The purpose of this request is to get the last trading price of a specific stock, in this case Disney (DIS).
The program that sends this message only needs to understand how to frame a request in a SOAP-compliant XML message and how to send it through HTTP. In the following example, the program knows how to format a request for a stock price. The HTTP server that receives the message knows that it is a SOAP message because it recognizes the HTTP header SOAPAction. The server then processes the message.
SOAP defines two types of messages, calls and responses, to allow clients to request remote procedures and to allow servers to respond to such a request. The previous example is an example of a call. The following example comes as a response in answer to the call.
Sample Response
The first three lines of code are standard HTTP. The first line indicates a response code to the previous POST request, the second and third lines indicate the content type and the fourth line the length of the response.
XML headers enclose the actual SOAP payloads. The XML element GetLastTradePriceResponse contains a response to the request for a trading price. The child element is Price, which indicates the value that is returned to the request.
SOAP building blocks and message structure example
Simple Object Access Protocol, as a specification, defines SOAP messages that are sent to web services and client applications. SOAP messages are XML documents that are comprised of the following three basic building blocks:
The SOAP Envelope encapsulates all the data in a message and identifies the XML document as a SOAP message.
The Header element contains additional information about the SOAP message. This information could be authentication credentials, for example, which are used by the calling application.
The Body element includes the details of the actual message that need to be sent from the web service to the calling application. This data includes call and response information.
The fault message is an optional fourth building block. If a SOAP fault is generated, it is returned as an HTTP 500 error. Fault messages contain a fault code, string, actor, and detail.
How does SOAP work?
SOAP advantages and disadvantages
The advantages of SOAP include the following:
Platform- and operating system-independent. SOAP can be carried over a variety of protocols, enabling communication between applications with different programming languages on both Windows and Linux.
Works on the HTTP protocol. Even though SOAP works with many different protocols, HTTP is the default protocol used by web applications.
Disadvantages, however, include the following:
No provision for passing data by reference. This can cause synchronization issues if multiple copies of the same object are passed simultaneously.
SOAP APIs
Skeleton SOAP Message
The SOAP Envelope Element
The required SOAP Envelope element is the root element of a SOAP message. This element defines the XML document as a SOAP message.
Example
The xmlns:soap Namespace
Notice the xmlns:soap namespace in the example above. It should always have the value of: "http://www.w3.org/2003/05/soap-envelope/".
The namespace defines the Envelope as a SOAP Envelope.
If a different namespace is used, the application generates an error and discards the message.
The encodingStyle Attribute
The encodingStyle attribute is used to define the data types used in the document. This attribute may appear on any SOAP element, and applies to the element's contents and all child elements.
A SOAP message has no default encoding.
Syntax
soap:encodingStyle="URI"
Example
The SOAP Header Element
The optional SOAP Header element contains application-specific information (like authentication, payment, etc) about the SOAP message.
If the Header element is present, it must be the first child element of the Envelope element.
Note: All immediate child elements of the Header element must be namespace-qualified.
The example above contains a header with a "Trans" element, a "mustUnderstand" attribute with a value of 1, and a value of 234.
SOAP defines three attributes in the default namespace. These attributes are: mustUnderstand, actor, and encodingStyle.
The attributes defined in the SOAP Header defines how a recipient should process the SOAP message.
The mustUnderstand Attribute
The SOAP mustUnderstand attribute can be used to indicate whether a header entry is mandatory or optional for the recipient to process.
If you add mustUnderstand="1" to a child element of the Header element it indicates that the receiver processing the Header must recognize the element. If the receiver does not recognize the element it will fail when processing the Header.
Syntax
soap:mustUnderstand="0|1"
Example
The actor Attribute
A SOAP message may travel from a sender to a receiver by passing different endpoints along the message path. However, not all parts of a SOAP message may be intended for the ultimate endpoint, instead, it may be intended for one or more of the endpoints on the message path.
The SOAP actor attribute is used to address the Header element to a specific endpoint.
Syntax
soap:actor="URI"
Example
The encodingStyle Attribute
The encodingStyle attribute is used to define the data types used in the document. This attribute may appear on any SOAP element, and it will apply to that element's contents and all child elements.
A SOAP message has no default encoding.
Syntax
soap:encodingStyle="URI"
The SOAP Body Element
The required SOAP Body element contains the actual SOAP message intended for the ultimate endpoint of the message.
Immediate child elements of the SOAP Body element may be namespace-qualified.
Example
The example above requests the price of apples. Note that the m:GetPrice and the Item elements above are application-specific elements. They are not a part of the SOAP namespace.
A SOAP response could look something like this:
The SOAP Fault Element
The optional SOAP Fault element is used to indicate error messages.
The SOAP Fault element holds errors and status information for a SOAP message.
If a Fault element is present, it must appear as a child element of the Body element. A Fault element can only appear once in a SOAP message.
The SOAP Fault element has the following sub-elements:
<faultcode>
A code for identifying the fault
<faultstring>
A human readable explanation of the fault
<faultactor>
Information about who caused the fault to happen
<detail>
Holds application specific error information related to the Body element
SOAP Fault Codes
The faultcode values defined below must be used in the faultcode element when describing faults:
VersionMismatch
Found an invalid namespace for the SOAP Envelope element
MustUnderstand
An immediate child element of the Header element, with the mustUnderstand attribute set to "1", was not understood
Client
The message was incorrectly formed or contained incorrect information
Server
There was a problem with the server so the message could not proceed
The HTTP Protocol
HTTP communicates over TCP/IP. An HTTP client connects to an HTTP server using TCP. After establishing a connection, the client can send an HTTP request message to the server:
The server then processes the request and sends an HTTP response back to the client. The response contains a status code that indicates the status of the request:
In the example above, the server returned a status code of 200. This is the standard success code for HTTP.
If the server could not decode the request, it could have returned something like this:
SOAP Binding
The SOAP specification defines the structure of the SOAP messages, not how they are exchanged. This gap is filled by what is called "SOAP Bindings". SOAP bindings are mechanisms which allow SOAP messages to be effectively exchanged using a transport protocol.
Most SOAP implementations provide bindings for common transport protocols, such as HTTP or SMTP.
HTTP is synchronous and widely used. A SOAP HTTP request specifies at least two HTTP headers: Content-Type and Content-Length.
SMTP is asynchronous and is used in last resort or particular cases.
Java implementations of SOAP usually provide a specific binding for the JMS (Java Messaging System) protocol.
A SOAP Example
In the example below, a GetStockPrice request is sent to a server. The request has a StockName parameter, and a Price parameter that will be returned in the response. The namespace for the function is defined in "http://www.example.org/stock".
A SOAP request:
The SOAP response:
Last updated
