A Quick Primer on SOAP XML and XPath

Wow…how time flies J .We have already hit half the year without even realizing it. One of the most frequent questions I get is about SOAP so I figured I will touch a bit on XML and XPath since anyone working with web services has to deal with them at some stage. A SOAP message which is basically XML can be summed up in the following image:


The envelope element encapsulates all the other elements to form our SOAP message. Let’s walk through a sample SOAP response message and see what we can make of it:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <GetCityWeatherByZIPResponse xmlns="http://ws.cdyne.com/WeatherWS/">
         <GetCityWeatherByZIPResult>
            <Success>true</Success>
            <ResponseText>City Found</ResponseText>
            <State>VA</State>
            <City>Virginia Beach</City>
            <WeatherStationCity>Virginia Beach</WeatherStationCity>
            <WeatherID>2</WeatherID>
            <Description>Partly Cloudy</Description>
            <Temperature>78</Temperature>
            <RelativeHumidity>87</RelativeHumidity>
            <Wind>SE7</Wind>
            <Pressure>29.85R</Pressure>
            <Visibility/>
            <WindChill/>
            <Remarks/>
         </GetCityWeatherByZIPResult>
      </GetCityWeatherByZIPResponse>
   </soap:Body>
</soap:Envelope>

An XML document which has a “soap:Envelope” element as the topmost element indicates that it is a soap message. The envelope element has some attributes with the syntax xmlns:foo which is used to define the namespace. Namespaces are used to provide uniquely named elements and attributes. For example, if you have two sets of data returned in your response message and both the child elements had an object called ‘name’, we would be in a situation where reference to the ‘name’ element would be ambiguous. Defining a namespace for the two sets of data will remove this ambiguity when referencing the data. Soap envelopes will always use the namespace ‘www.w3.org/2003/05/soap-envelope’ to define it as a soap document. Any others namespaces will cause an error within CIC.

There are couple other namespaces usually defined in the envelope element. Typically, the xsd namespace (http://www.w3.org/2001/XMLSchema) is used to define the xml schema which describes the xml document while the xsi namespace (http://www.w3.org/2001/XMLSchema-instance) is used to define the location of the schema. The body of a soap document is where the data we have requested resides. Application specific namespaces are defined for the child element after the body. In our example, the namespace is set to ‘http://ws.cdyne.com/WeatherWS’.

Now that we somewhat understand what a soap message looks like, let’s have a brief look at XPath. XPath is a language for finding information in an XML document. You use an expression which points to the location of the data in the XML. The most common selection expression is ‘/’ which selects information from the root node.

A good way to write your XPath expression is to visualise your XML response in tree form e.g


So to retrieve the ‘State’ from our response message, we walk our way from the top and form our expression as:

/soap:Envelope/soap:Body/GetCityWeatherByZIPResponse/GetCityWeatherByZIPResult/State

Or we can shorten it to

//GetCityWeatherByZIPResponse/GetCityWeatherByZIPResult/State

But wait…there is a problem. The expression will not return any data. The ‘gotcha’ moment with our response message is that the namespace “xmlns=http://ws.cdyne.com/WeatherWS/” does not have a prefix for the declaration. By not defining a prefix, it is defaulting to the default namespace or null namespace and we cannot use XPath expressions to reference the null namespace. We can remove the namespace declaration or we can assign a prefix to make this work but since we are going to be using CIC to parse the incoming response, my next post will go over how we handle this scenario in our handlers and retrieve the data we want using XPath.

Until then, have a good day and I will look forward to some feedback.

-Anish

Anish Sharma

Anish Sharma

I joined Interactive Intelligence in July, 2011. Prior to that, I worked with an Elite partner for 11 years. Over the years, I worked with various products from Interactive Intelligence, including support, implementation and development. A self-confessed geek, I enjoy taking things apart and figuring how it works. One of my passions is photography and I have a personal photo blog.