WebReference.com - Part 3 of Chapter 3: Professional XML Web Services, from Wrox Press Ltd (2/5) | WebReference

WebReference.com - Part 3 of Chapter 3: Professional XML Web Services, from Wrox Press Ltd (2/5)

To page 1current pageTo page 3To page 4To page 5
[previous] [next]

Professional XML Web Services

SOAPAction Header

The SOAP specification does define a single additional HTTP header to be used when SOAP messages are transported over HTTP, and that header is the SOAPAction header. The SOAPAction header provides a hint to servers that a particular HTTP POST contains a SOAP message, and the value of the header is a URI that indicates the intent of the SOAP message. This allows firewalls and other servers to perform conditional processing based on the presence of the SOAPAction header.

Version 1.1 stated that the SOAPAction header must be present in HTTP transports, although it may be blank. Since then, that requirement has been removed. A blank SOAPAction on an HTTP POST means that the intent of the message can be inferred from the target of the POST, the URI. Although this may sound confusing, it is actually pretty straightforward. There are some messages whose purpose is obvious by where they are going (what URL they are posted to). If our methods are implemented at one URL, we may need to use the SOAPAction header to make the intent of an incoming message clearer. The need for SOAPAction largely depends on how the endpoint is implemented.

Status Codes

You will recall that HTTP returns status information in the form of status codes. These codes are integers, and they are sectioned into classes of 100. For example, anything in the range 200-299 indicates success. SOAP places a requirement on the HTTP transport when it is used to exchange SOAP messages. If the response message contains a fault, then the status code of the HTTP response must be 500, which indicates an Internal Server Error. We will see examples of both success and failure status codes later in the chapter.

Let's take a look at the response to our GetSecretIdentity call (below) to see the relationship between request and response, as well as message and fault.

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: ###
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" 
               soap:encodingStyle="https://schemas.xmlsoap.org/soap
                                   /encoding/" 
               xmlns:xsi="https://www.w3.org/1999/XMLSchema-instance"
               xmlns:xsd="https://www.w3.org/1999/XMLSchema">
   <soap:Body>
      <m:GetSecretIdentityResponse xmlns:m="https://www.wrox.com/heroes/">
         <return xsi:type="xsd:string">Michael Kay</return>
      </m:GetSecretIdentityResponse>
   </soap:Body>
</soap:Envelope>

The above response is successful, returning the identity of Wrox's resident XSLT super-hero. Notice the first line of the example response, which contains the status code 200. Now, let's call the GetSecretIdentity method again, but this time we will send a different request, one with problems:

POST /endpoint.asp HTTP/1.1
Content-Type: text/xml
Content-Length: ###
SOAPAction: "urn:wroxheroes"
<Envelope>
   <Body>
      <w:GetSecretIdentity xmlns:w="https://www.wrox.com/heroes/">
         <codename>XSLT-Man</codename>
      </w:GetSecretIdentity>
   </Body>
</Envelope>

In this case, the SOAP namespace is missing completely, so the endpoint must return a fault, which means it must use a status code of 500 on the response. The response message is shown below, and it contains a VersionMismatch fault as well as the appropriate status code:

HTTP/1.1 500 Internal Server Error
Content-Type: text/xml
Content-Length: ###
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
               soap:encodingStyle="https://schemas.xmlsoap.org/soap
                                   /encoding/" 
               xmlns:xsi="https://www.w3.org/1999/XMLSchema-instance"
               xmlns:xsd="https://www.w3.org/1999/XMLSchema">
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:VersionMismatch</faultcode>
            <faultstring>The SOAP namespace is incorrect.</faultstring>
         <faultactor>https://www.wrox.com/endpoint.asp</faultactor>
         <detail>
            <w:errorinfo xmlns:w="https://www.wrox.com/">
               <desc>The SOAP namespace was blank.</desc>
            </w:errorinfo>
         </detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

These examples show how to use HTTP as the transport binding for SOAP. It is not difficult to use HTTP, which is one of the reasons for its popularity. For more information on HTTP, including the status codes, consult Chapter 2.

If we think of transport as "how" the message is sent, then the purpose of the message is the "why". HTTP is SOAP's "how" of choice for the time being, and our next topic, RPC, is the "why".


To page 1current pageTo page 3To page 4To page 5
[previous] [next]

Created: November 26, 2001
Revised: November 26, 2001


URL: https://webreference.com/authoring/languages/xml/webservices/chap3/3/2.html