WebReference.com - Part 3 of Chapter 3: Professional XML Web Services, from Wrox Press Ltd (2/5)
Professional XML Web Services
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
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
to make the intent of an incoming message clearer. The need for
SOAPAction largely depends
on how the endpoint is implemented.
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="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap /encoding/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"> <soap:Body> <m:GetSecretIdentityResponse xmlns:m="http://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
POST /endpoint.asp HTTP/1.1 Content-Type: text/xml Content-Length: ### SOAPAction: "urn:wroxheroes" <Envelope> <Body> <w:GetSecretIdentity xmlns:w="http://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="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap /encoding/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"> <soap:Body> <soap:Fault> <faultcode>soap:VersionMismatch</faultcode> <faultstring>The SOAP namespace is incorrect.</faultstring> <faultactor>http://www.wrox.com/endpoint.asp</faultactor> <detail> <w:errorinfo xmlns:w="http://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".
Created: November 26, 2001
Revised: November 26, 2001