Friday, 2 March 2012

SOAP - A Complete Low-Level Guide to the Technology

I have been using SOAP for a number of years now (lol), mainly SOAP based services within the .NET architecture. However, i've never really sat down and drilling into the inner workings on a lower level.


SOAP (Simple Object Access Protocol)
- Used to accomplish internet communication between systems (software, programs, web apps, services etc.)
- HTTP is supported by all internet browsers and servers.
- SOAP therefore uses HTTP to enable this communication.
- SOAP relies on XML for its messaging format.
- Simple!


Common Misconceptions
- There is no such thing as a SOAP Protocol... It's more of a schema (a subset of XML). Therefore, SOAP based web services will typically use HTTP (Port 80) or HTTPS (Port 443).


Architecture
- A SOAP request could be a HTTP GET or a HTTP POST. For example, a HTTP POST request specifies at least two HTTP headers: Content-Type and Content-Length.
- When a GET/POST request is made to a SOAP based web service, the HTTP message will detail two parts: Header information (content length/type, host etc...) and a SOAP Envelope (All in XML)...

Here is a sample HTTP POST request using SOAP...

Code Snippet
  1. POST /InStock HTTP/1.1
  2. Host: www.example.org
  3. Content-Type: application/soap+xml; charset=utf-8
  4. Content-Length: nnn
  5.  
  6. <?xml version="1.0"?>
  7. <soap:Envelope
  8. xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
  9. soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
  10.  
  11. <soap:Body xmlns:m="http://www.example.org/stock">
  12.   <m:GetStockPrice>
  13.     <m:StockName>IBM</m:StockName>
  14.   </m:GetStockPrice>
  15. </soap:Body>
  16.  
  17. </soap:Envelope>
End of Code Snippet


Once the service has processed the request, it will provide a response back in the following format...


Code Snippet
  1. HTTP/1.1 200 OK
  2. Content-Type: application/soap+xml; charset=utf-8
  3. Content-Length: nnn
  4.  
  5. <?xml version="1.0"?>
  6. <soap:Envelope
  7. xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
  8. soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
  9.  
  10. <soap:Body xmlns:m="http://www.example.org/stock">
  11.   <m:GetStockPriceResponse>
  12.     <m:Price>34.5</m:Price>
  13.   </m:GetStockPriceResponse>
  14. </soap:Body>
  15.  
  16. </soap:Envelope>
End of Code Snippet



SOAP Envelope Architecture
A SOAP envelope details header information, message body and any fault codes or statues that may occur/exist. Full schema can be found here: http://www.w3.org/2001/12/soap-envelope



Header (Optional)

Typically, the header is used to hold security information, I.e. authentication into the target system.


Body (Required)

The message body is used to hold all information passed or received from the SOAP service. This includes: Methods, parameters, return values etc...


Example

The Request may look like this...
Code Snippet
  1. <soap:Body>
  2.   <m:GetPrice xmlns:m="http://www.w3schools.com/prices">
  3.     <m:Item>Apples</m:Item>
  4.   </m:GetPrice>
  5. </soap:Body>
End of Code Snippet


Once the service has finished processing, probably by checking a database for the price of apples, the SOAP service will return the following message body...

Code Snippet
  1. <soap:Body>
  2.   <m:GetPriceResponse xmlns:m="http://www.w3schools.com/prices">
  3.     <m:Price>1.90</m:Price>
  4.   </m:GetPriceResponse>
  5. </soap:Body>
End of Code Snippet


Fault Codes (Optional - Contained in the SOAP Body)
Fault codes are used to indicate error messages. They are entirely optional. If a fault code is present, it will contain the following information: faultcode, faultstring, faultactor, detail.

The following XML displays an example of a SOAP fault in a SOAP response message.

Code Snippet
  1. <soap:Body>
  2.     <soap:Fault>
  3.         <faultcode xsi:type="xsd:string">soap:Client</faultcode>
  4.         <faultstring xsi:type="xsd:string">
  5.             Failed to locate method (ValidateCreditCard) in class
  6.             (examplesCreditCard) at /usr/local/ActivePerl-5.6/lib/
  7.             site_perl/5.6.0/SOAP/Lite.pm line 1555.
  8.         </faultstring>
  9.     </soap:Fault>
  10. </soap:Body>
End of Code Snippet


Interoperability
So if your wondering how the heck you can utilise this technology, you already know it's used to solve communication between programs over HTTP, so here's an example...

1. You wish to create a website that displays the latest weather information on the homepage.

2. Rather than spending thousands of pounds/dollars/euro on weather equipment (and learning how to use it!), you decide it would be better to import data from an external website.

3. Rather than "Screen Scraping" (stripping weather information out of the HTML), if we could tap right into their data store, we can display the information however we would like.

4. We now need to find a weather site that exposes a SOAP service for us to consume'... Visit: http://www.service-repository.com/ this is a good public listing of popular SOAP web services.

5. You may see GlobalWeather on the homepage. They provide a nice and easy to use SOAP service to access weather information based on city and country: http://www.webservicex.com/globalweather.asmx... It exposes two methods: GetCitiesByCountry and GetWeather.

6. By clicking on one of these methods, you can view the sample SOAP request and response messages. This provides you with how your HTTP Request should be formatted for the SOAP service to understand your request. It also tells you (from the response) what to expect back from the service. Simple!


NOTE: By understanding the inner workings of SOAP, you can call SOAP services from programming languages/environments that may not DIRECTLY support web service proxies (I.e. iPhone/iOS, Python etc...). So by sending a SOAP request using a standard HTTP Request (which most languages do support), you can achieve the same result.

No comments: