SOAP

SOAP was originally an acronym for Simple Object Access Protocol. That stood well through version 1.1 of the protocol itself. Many companies contributed to the wording in that specification—IBM, Microsoft, DevelopMentor, Ariba, Compaq, Hewlett Packard, Commerce One, IONA, Lotus, and SAP AG. Soon after that release, Web Service adoption began in earnest. More and more people saw that something originally developed for simple object access and remote procedure calls could be used as a general purpose messaging system. Using SOAP, you can exchange any data that can be expressed in XML.

A SOAP message has the following major elements:

• Envelope Contains the SOAP message

• Header Contains message metadata, such as authentication information

• Body Contains the main data being sent in the message

• Fault Communicates any errors that occurred while processing the SOAP message

You will examine these elements within the context of a typical SOAP message being sent over HTTP, as shown in Listing 3.1.

Request:

Listing 3.1. Complete HTTP Exchange for a SOAP Message

POST /CHapter6CustomAuthen/Authenticate.asmx HTTP/1.1

User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; MS Web Services Client Protocol 1.0.3328.2)
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://www.samspublishing.com/ch6ex1/HelloWorld"
Content-Length: 709
Expect: 100-continue
Host: localhost

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:tns="http://www.samspublishing.com/ch6ex1"
    xmlns:types="http://www.samspublishing.com/ch6ex1/encodedTypes"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Header>
        <tns:TokenHeader id="id1" 
            soap:mustUnderstand="1"
            soap:actor="http://schemas.xmlsoap.org/soap/actor/next">
            <theToken xsi:type="xsd:string">this_is_the_token</theToken>
        </tns:TokenHeader>
    </soap:Header>
    <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <tns:HelloWorld />
    </soap:Body>
</soap:Envelope>

Response:

HTTP/1.1 200 OK
Server: Microsoft-IIS/5.1
Date: Sun, 07 Oct 2001 00:54:45 GMT
Cache-Control: private, max-age=0
Content-Type: text/xml; charset=utf-8
Content-Length: 591

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:tns="http://www.samspublishing.com/ch6ex1"
    xmlns:types="http://www.samspublishing.com/ch6ex1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <types:HelloWorldResponse>
            <HelloWorldResult xsi:type="xsd:string"
               >Hello World!</HelloWorldResult>
        </types:HelloWorldResponse>
    </soap:Body>
</soap:Envelope>

In the rest of this section, you will examine the message and explain all of its various parts.

SOAPAction

The first SOAP-specific item you see in the header section of the HTTP request is the SOAPAction HTTP header. This header was originally included to indicate the intent of the SOAP message. The thinking went that by using this header, network administrators could grant or deny access to certain callers. SOAP v1.2 has a better solution—let the URL indicate the intent. The URL of the SOAP endpoint can be formed to contain the same amount of meaning as the SOAPAction header. As an added benefit, most networking hardware and software already have mechanisms in place to deal with URL based filtering.

Envelope

All SOAP messages have an Envelope element as the document root. The namespace used to qualify this element also serves to indicate the SOAP version. Version 1.1 SOAP messages use the http://schemas.xmlsoap.org/soap/envelope/namespace. When version 1.2 of the SOAP specification rolls out in the middle of 2002, it will have a different namespace. The working draft of the specification states that the namespace is http://www.w3.org/2001/09/soap-envelope. When the recommendation is passed, the version will most likely be http://www.w3.org/2002/soap-envelope.

Other than supplying versioning information, most SOAP envelopes also contain XML Namespace declarations that may be used in the rest of the message. You will often see namespace declarations that define the version of XSD being used to communicate type information. Those namespaces are as follows:

• XSD Instance data: http://www.w3.org/2001/XMLSchema-instance

• XSD Schema data: http://www.w3.org/2001/XMLSchema

The ASP .NET implementation always includes a definition for the XSD namespaces, even if they are not used by the message.

Header

The Header is used to communicate “out of band” data. Typically, you will see the Header used to include information about the caller's identity, any transactions the message might be involved in, or information that various intermediaries might need. A number of specifications use the SOAP Header for their information.

A client can put any number of elements within the Header. Each element that is an immediate child of the Header can use two attributes: mustUnderstand and actor. mustUnderstand indicates whether a recipient of the message must understand the particular Header element. If it does not understand the Header element, the server must return a MustUnderstand Fault. In SOAP v1.1, mustUnderstand uses the value 0 to tell the server that it does not need to handle the particular Header element to process the message and 1 to tell the server that it must understand the element. In SOAP v1.2, the values true and false are also allowed because mustUnderstand is defined as a Boolean. An XSD Boolean type allows the values 1 or true and 0 or false.

Body

The Body element typically contains the main information being sent by the SOAP message. Within this element, almost anything goes. When doing remote procedure calls over SOAP, the main element in the message is typically the name of the method being called. Normally, the response to that message is named MethodNameResponse. Within that element, you will find parameters and, optionally, type information. The type information helps to deserialize the message into the correct types when the message format is unknown. Because most toolkits rely on WSDL documents, the client and server know the types of the elements and their names long before any message exchanges occur.

When used to send information, the SOAP Body can declare that the data uses a specific encoding style. This is specified by using the encodingStyle attribute. If you are using the encoding style supported by the SOAP specification, you will see the encodingStyle attribute set to the http://schemas.xmlsoap.org/soap/encoding/URI. The final version of the SOAP v1.2 recommendation will probably specify the SOAP encoding style URI as http://www.w3.org/2002/soap-encoding. What does this encoding style mean to you? It means that every element in the message has its type specified as an XSD instance data type.

You can also use SOAP to send XML documents to a recipient. In this case, the Body just contains the document and the SOAP protocol serves as a way to get the document to an endpoint that can understand it.

Fault

As with all applications, errors can and will happen in SOAP. SOAP uses the Fault element to communicate those errors. When a SOAP Fault is present, it must appear in the SOAP Body. This is true if a Header element is not understood or if the Body has something messed up. Fault elements have the following sub-elements:

• faultcode States why the fault occurred. It is meant to be used by other machines to algorithmically determine what went wrong. This element is required.

• faultstring Provides a human readable explanation of the faultcode. This element is required.

• faultactor This element indicates the URI of the entity that encountered the error. It is optional when the entity discovering the error is the ultimate endpoint, and it is required when the SOAP error is discovered by an intermediate processor. SOAP allows for multiple entities to handle fulfillment of a message.

• detail This must be present when the error resides in the Body element. It cannot be used to carry information about errors in Header entries. Error details regarding Header entries must be carried in the Header.

The faultcode might contain one of the following values:

• VersionMismatch The version of the SOAP envelope is not understood by this endpoint.

• MustUnderstand The Header contains an element marked as mustUnderstand that the endpoint does not understand.

• Client An error exists in the message and that error originated with the client. Sending the message again will result in another failure.

• Server An error occurred on the server side of the message exchange. The client should expect to see the message succeed if the message is sent again after a short delay.

All of the faultcode elements can be expanded on using a dot notation. For example, to tell the client that an error exists in the expected type for the arg1 element expressed by the doIt method, the faultcode could be expressed as Client.doIt.arg1.

SOAP v1.2 adds one more faultcode to the mixture—DataEncodingUnknown. If the message specifies the encodingStyle attribute on the Body or on a Header element and that encoding style is not supported by the endpoint, the endpoint will return a DataEncodingUnknown faultcode. (In SOAP v1.1, the endpoint would return a Client fault.)