11 - Anatomy of a SOAP Message

Hi,

We know that in Web Services, ‘SOAP Message’ is the core part in commmunication,

Cleint à Call on Proxy à Serialize à Soap Message à Encrypt à Sent to Server

Server à Decrypt à Deserialize à Actual WebService Object à Execute the Method

Server à Call on Proxy à Serialize à Soap Message à Encrypt à Sent to Server

Client à Decrypt à Deserialize à Return value to ProxyObject -> ProxyObjec sends value to Client

Here we’ll study the core of SOAP Message.

Anatomy of a SOAP Message:

Here we’ll discuss below:

· SOAP Envelop

· SOAP Encoding

· Protocol Binding

SOAP Envelop:

· A SOAP message is composed within a wellformed SOAP Envelope.

· An SOAP envelope is composed of a single Envelope element.

· The envelope can contain a Header element and must contain a Body element. i.e Body (Mandatory) & Header (Optional).

· If present, the header must be the immediate child element within the envelope, with the body immediately following the header.

· A valid SOAP message can also contain other child elements within the envelope.

· The Body element contains the data specific to the message.

· The Header Element contains information about the message. In the preceding example, the header contains two elements describing the individual who composed the message and the intended recipient of the message.

· Notice that each SOAP-specific element has the soap namespace prefix.

· This prefix is defined within the Envelope element and points to the SOAP schema that describes the structure of a SOAP message.

· The soap prefix indicates that the Envelope element is an instance of the SOAP Envelope type.

SOAP Actors

· A SOAP actor is anything that acts on the content of the SOAP message.

· There are two types of SOAP actors.

· Default Actors – The default actor is the intended final recipient of a SOAP message.

· Intermediaries -

An intermediary receives a SOAP message and might act on the before forwarding it along the intended message path.

Even though intermediaries might modify the data transferred from the client to the default actor, it is still considered the same message.

The Header Element (Optional)

· Is used to pass data that might not be appropriate to encode in the body. For e.g Security digest information, Routing information etc

<soap:Header>

   <Digest>B839D234A3F87</Digest>

</soap:Header>

mustUnderstand Attribute

· Because headers are optional, the recipient of the message can choose to ignore them.

· However, some information should not be ignored by the intended recipient. Therefore, to distinguish header information that is informative, use this attribute.

<soap:Header>

   <TransactionId soap:mustUnderstand="1" actor="urn:TransactionCoordinator>123</TransactionId>

</soap:Header>

actor Attribute

· We know that - SOAP message can be routed through many intermediaries before it reaches its final destination. (See above figure)

· The SOAP specification provides the actor attribute for targeting SOAP headers for certain intermediaries

· The value of this attribute is the URI of the intermediary for which the portion of the message is intended. If a header is intended to be processed by the next intermediary to receive the SOAP message, the actor attribute can be set to http://schemas.xmlsoap.org/soap/actor/next. Otherwise the actor attribute can be set to a URI that identifies a specific intermediary.

<soap:Header>

   <TransactionId soap:mustUnderstand="1" actor="urn:TransactionCoordinator>123</TransactionId>

</soap:Header>

Note:

If the message is passed to another recipient, any header elements designated for the intermediary must be removed before the message is forwarded.

The intermediary can, however, add additional header elements before forwarding the message to the next recipient.

The Body Element

· A valid SOAP message must have one Body element.

· There are no restrictions on how the body can be encoded. The message can be a simple string of characters, an encoded byte array, or XML.

· The only requirement is that the contents cannot have any characters that would invalidate the resulting XML document.

· SOAP messages can generally be placed into two categories: Procedure- Oriented Messages and Document-Oriented Messages.

· Procedure-oriented messages provide twoway communication and are commonly referred to as remote procedure call (RPC) messages. The body of an RPC message contains information about the requested action from the server and any input and output parameters.

· Document-oriented messages generally facilitate one-way communication. Business documents such as purchase orders are examples of document-oriented messages.

Fault Element

· Everything does not always go as planned. Sometimes the server will encounter an error while processing the client’s message.

· SOAP provides a standard way of communicating error messages back to the client.

<soap:Body>

<soap:Fault>

<soap:faultcode>Client.Security</soap:faultcode>

<soap:faultstring>Access denied.</soap:faultstring>

<soap:faultactor>http://abc.com</soap:faultactor>

<soap:detail>

<MyError>

<Originator>File System</Originator>

<Resource>MySecureFile.txt</Resource>

</MyError>

</soap:detail>

</soap:Fault>

</soap:Body>

· The fault code contains a value that is used to programmatically determine the nature of the error. The SOAP specification defines a set of fault codes as below.

Fault Code
VersionMismatch
MustUnderstand
Client
Server

· You can append more specific fault codes to the core SOAP fault codes listed in the table by using the “dot” notation and ordering the individual fault codes from least specific to most specific.

· For example, if the server is unable to open a database connection that is required to process the client’s message, the following fault code might be generated:

<faultcode>Server.Database.Connection</faultcode>

SOAP Encoding:

· SOAP Encoding defines the way data can be serialized within a SOAP message.

· SOAP Encoding builds on the types, defined in the XML specification, which defines a standard way of encoding data within an XML document.

· SOAP Encoding provides a standard means of serializing data types that are not defined within part 1 of the XML Schema specification. This includes arrays and references to instances of data types.

Simple Types

An instance of a data type is encoded as an XML element.

For example, an integer called Age would be encoded as: <Age>31</Age>

Compound Types - Structures

public struct RectSolid { public int length; public int width; public int height; } public int CalcVolume(RectSolid r) { return (r.length * r.width * r.height); }

<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <CalcVolume> <r> <length>2</length> <width>3</width> <height>1</height> </r> </CalcVolume> </soap:Body> </soap:Envelope>

Protocol Binding

· After we properly encode a SOAP message, we need a way to send the message to the remote application.

· Arguably the most popular transport protocol used to send SOAP messages is HTTP.

· However SOAP is is not tied to a particular transport protocol. SOAP messages can be sent over any transport protocol that is capable of carrying XML. Few of them are SMTP, via fax, to a ship at sea via a shortwave radio, or whatever else can be dreamed up.

· The SOAP specification describes only one protocol binding: sending SOAP messages via HTTP POST. Therefore, the only protocol binding we’ll discuss is HTTP POST.

Defn:

· How a SOAP message is carried by a particular transport protocol is known as the Protocol Binding.

· A protocol binding can be defined to exploit any unique characteristics of the transport protocol. For .e.g. the HTTP POST binding can extend the protocol so that HTTP-aware firewalls have the ability to filter SOAP messages.

HTTP POST:

Below is an example of an HTTP Request & Response.

HTTP Request -

· Contains a SOAP message.

· An HTTP request is composed of two parts, a header and a body.

· The header contains information about the request and about the client that sent the request.

· The body follows the header and is delimited by two carriage-return/ linefeed pairs. The body contains the SOAP message.

· The Content-Type header entry is always set to text/xml.

· The SOAPAction header entry is used to communicate the intent of the SOAP message.

o The URI can be represented in any format and is not required to be resolvable.

o The value of the SOAPAction header can be blank if the intent of the SOAP message is conveyed in the HTTP request header entry.

o The HTTP request header entry is the first entry in the header and contains the action (in this case, always POST) and the targeted URI.

o If the URI in the HTTP request header entry adequately communicates the intent of the SOAP message, then leaving SOAPAction blank will do.

POST /TrialService/Service.asmx HTTP/1.1

Host: localhost

Content-Type: text/xml; charset=utf-8

Content-Length: length

SOAPAction: "http://tempuri.org/HelloWorld"

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<HelloWorld xmlns="http://tempuri.org/" />

</soap:Body>

</soap:Envelope>

HTTP Response -

· Used to communicate the results of the SOAP request

· MIME type is set to text/xml

· For RPC-style messages, the HTTP body contains the SOAP response message. Otherwise, the HTTP body would be empty.

· The status reported in the first line of the HTTP header must contain a value between 200 and 299. In the event of an error while processing the SOAP message, the HTTP status must be 500, indicating that an internal server error occurred.

HTTP/1.1 200 OK

Content-Type: text/xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<HelloWorldResponse xmlns="http://tempuri.org/" />

</soap:Body>

</soap:Envelope>

Thanks & Regards,

Arun Manglick || Senior Tech Lead