Webservices Simplified - Layman Understanding, And How To Use Webservices

I had always known about web services and a few of the hundred thousand acronyms associated with the web services ecosystem, but I had never really written code to use them. I avoided working with them because I don’t know why I always thought of them what any protester thinks of a Government. Ok, I just said I don’t know why I thought that way so you are free to assume your reasons, and most of them, I fear, would be right. But it was just a matter of time before I could not avoid working with web services any longer and was about to get to know them for real. They are far from anything as boring and clunky as Governments across our planet. On the contrary, they are an easy and powerful and even quite fun. And now that I don't hate and avoid web services anymore, I must share what good things I know about them and the advantages of web services.

I am a sucker for simplifying all things, especially stuff related to technology, except when I am in the mood for some geekiness :-) So don't be surprised if the answers and information you find here sound different (read:layman-ish) from what you are used to finding most other places.

What is a webservice?

A webservice is any piece of software, that provides some functionality, is available over the internet, and talks using standardized XML.

The ‘standardized’ part in the answer above makes web services seemingly boring, but that is so only when you have got a wrong perspective of things. Standardization here has immense benefits and is what makes web services such a neat idea. Let me show you how -

• Let ‘you’ = you OR any application OR just a piece of code OR something else. Now...
• You can talk to a webservice over the network via HTTP, SMTP, FTP, BEEP and many other protocols.
• When you talk to a webservice, the ‘talk’ part is done using XML in a standardized fashion. The current standardized fashion being XML-RPC and SOAP.
• All stuff that a webservice would do for you (functionality provided) and all things it would need from you to do so (expected input) is described in XML in a standardized way called WSDL.
• Webservices live in registries in a way such that the right one for the job can be very easily found. This is made possible by another standardized XML way called UDDI.
• XML is the music which makes web services dance.

All these pointers above are the real fundamental ideas associated with web services, but of course, I would encourage you to learn more things and in detail -

• Best FAQ I could find on web services - http://www.webservicex.net/WS/faq.aspx
• A blessing of an article demystifying acronyms associated with web services and more -http://www.xml.com/lpt/a/888

Getting started with web services - a hands-on

Say we are in need of fetching stock quotes of a publicly-traded company and use the data in some in our application. We could search for web services that allow us to do just that on public webservice repositories such as http://www.service-repository.com/ and http://www.webservicex.net/WS/wscatlist.aspx. Or you could request access to use paid web services, for example, Reuters has a very comprehensive paid webservice that provides all imaginable functionality related to stock and financial markets.

Let's use the ‘stock quote’ webservice here - http://www.webservicex.net/WS/WSDetails.aspx?WSID=9&CATID=2 that is present in the later public repository. And let's get this task done using the popular HTTP::Request module for Perl (this and more ways of working with web services, web services types and how webservice works are covered later in this post)

How to understand the webservice?

Everything that needs to be understood about a webservice -

• What methods does a webservice provide?
• What parameters are expected by which methods?
• What modes of communication does the webservice provide?
• How should the SOAP request look like?
• etc..

is present in the WSDL file of the webservice.

For example, look inside the WSDL file of Stock Quote webservice that we are using for this hands-on - http://www.webservicex.net/stockquote.asmx?WSDL. Now that is not what you would call readable. Well, it is not meant to be so for humans. But various applications understand them pretty well. You could use tools that read a WSDL file and give you the answer for all the above questions, such as - http://wscep.sourceforge.net/createrequest.html

Almost all web services come with documentation that tells you how to make a request to a specific method of the service. And if they don't, you could always use tools that read and understand WSDLs for you. In our case, the documentation for Stock Quotes webservice is present here - http://www.webservicex.net/stockquote.asmx?op=GetQuote and tells us to send the below SOAP request to get quote data

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<br />&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;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/"&gt;
  &lt;soap:Body&gt;
    &lt;GetQuoteResponse xmlns="http://www.webserviceX.NET/"&gt;
      &lt;GetQuoteResult&gt;string&lt;/GetQuoteResult&gt;
    &lt;/GetQuoteResponse&gt;
  &lt;/soap:Body&gt;
&lt;/soap:Envelope&gt;

How to send a request to a webservice?

To create a SOAP request that will be POSTed to the webservice over HTTP, we need to know a few values such as ‘SOAPAction’ in the example request above. This value can be found from the documentation or by looking at the WSDL file manually or using a tool. For example, the value of SOAPAction for a particular method can be quickly found by searching for the text soapaction in the WSDL file and checking if it is associated with the method you are concerned with by looking at the parent ‘wsdl:operation’ element.

Once we have all the values we would make the actual request in Perl as shown below -

 # Including the required modules
use LWP::UserAgent;
use HTTP::Request;
use XML::Simple;
<br /># Creating the request string
my $message = '&lt;?xml version="1.0" encoding="utf-8"?&gt;<soap envelope xsi="http://www.w3.org/2001/XMLSchema-instance" xsd="http://www.w3.org/2001/XMLSchema" soap="http://schemas.xmlsoap.org/soap/envelope/"><soap body><symbol>GOOG</symbol></soap></soap>';
<br /># Creating the request headers
my $userAgent = LWP::UserAgent-&gt;new();
my $request = HTTP::Request-&gt;new(POST =&gt; 'http://www.webservicex.net/stockquote.asmx');
$request-&gt;header(SOAPAction =&gt; '"http://www.webserviceX.NET/GetQuote"');
$request-&gt;content_type("text/xml; charset=utf-8");
<br /># Creating the request body
$request-&gt;content($message);
<br /># Making the request and storing the response
my $response = $userAgent-&gt;request($request);

How to parse the response received from the webservice?

Since we sent the SOAP request over HTTP the response received is similar to any HTTP response. It would have a status code (200 = error, 404 = not found, 403 = forbidden etc), and headers and a body.

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<br />&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;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/"&gt;
  &lt;soap:Body&gt;
    &lt;GetQuoteResponse xmlns="http://www.webserviceX.NET/"&gt;
      &lt;GetQuoteResult&gt;<font class="value">string</font>&lt;/GetQuoteResult&gt;
    &lt;/GetQuoteResponse&gt;
  &lt;/soap:Body&gt;
&lt;/soap:Envelope&gt;

It is important to note that the response code of 200 indicates that the webservice returned something. That could be the data we were looking for or could be an error message indicating timeout, incorrect parameters etc. Anyway, once the response is in, it can be parsed just as any XML

if($response->code == 200) {
    my $xml = new XML::Simple;
    my $data = $xml->XMLin($response->content);
    # Do what you want to do with the data, now present in the hash $data
}
else {
    print $response->error_as_HTML;
}

Creating your own web service

This post covered a basic introduction to web services and how to consume them. Providing web services or making our application such that they can be consumed by others in a similar fashion is about just as easy. You might want to look at SOAP::Lite Perl module for quick hands-on. I have done my ‘hello worlds’ with it and its quite easy.

FTW

1. I had presumed web services are a thing of past - BUT it turns out they are not too different from the in fashion enterprise-friendly SOA, the modern web APIs, etc. And they are still the best solution for things such as database abstraction -http://stackoverflow.com/questions/2142070/why-should-a-developer-use-we...
2. I had presumed web services are hard to use - BUT it turns out I was able to learn and understand interesting things about them (I am sure there is a lot of uninteresting stuff that I do not care about right now), write about 20 different scripts to pull all kinds of stock-related data from Reuters web service, fetch and process millions of records and more, all in no time. That added yet another happy customer to Innoraft :-)