SolutionsWeb ServicesWS Client Exercise

 Google is no longer issuing new IDs for the Google SOAP Search API. If you already have an ID issued by Google, the API is still operational and you can follow the exercise as described below. If you do not have an ID for the Google SOAP Search API, the exercise can still serve as a step-by-step guide to developing your own Web Service client interface with XMLSpy.

While the other pages in this section discuss building a Web service from end to end, here we explain how you can gain experience by using the Web services tools in XMLSpy to connect to a Web service that is already available over the Internet. You can create Web service SOAP requests, send them to the live Web service, and examine the responses.

A whole spectrum of Web services are available, some offered by Internet industry leaders such as Google®, eBay®, Amazon®, Yahoo!®, and others. Their APIs describe how outside enterprises or individuals can employ these Web services to integrate and customize some of each company's business functionality into new Web sites or custom applications.

As an example, we'll outline the steps here to craft a simplified search utility inside XMLSpy by connecting to the GoogleSearch Web service. If you don't already have it, download XMLSpy® 2008 Enterprise Edition now and follow along.

Google offers the GoogleSearch API for non-commercial use to holders of a free Google account. This means the Web service itself is public, but the account key limits access to known users only. Each Web services request must include a valid account key as one of its parameters. You can register for an account and get full details of the GoogleSearch Web service on Google's site. The GoogleSearch API is a free service available only for non-commercial use and is subject to Google’s terms of service.

(If you don't want to register with Google, there is a detailed Web services tutorial in the XMLSpy Online Help section that connects to a TimeService Web service that reports the current time in various time zones around the world.)

The WSDL that defines GoogleSearch is stored on the Google server running the Web service. We can open the WSDL by choosing the XMLSpy File/Open URL menu option:

Examining the WSDL in XMLSpy WSDL view, we see that it contains three operations listed on the right side under PortTypes:

• doGetCachedPage
• doSpellingSuggestion
• doGoogleSearch

Since searches on Google are a universally understood way to find information on the Web, the functionality of the doGoogleSearch Web service operation is easy to follow.

Now, to invoke the service, we'll select the XMLSpy SOAP menu and create a new SOAP request for the doGoogleSearch operation:

XMLSpy retrieves the remote WSDL and creates a SOAP request template for the doGoogleSearch operation, which we can examine in multiple views. Browser view displays the response with slightly different color coding than Text view. In Browser view the required search parameters are bold and black.

We can also expand the request in the XMLSpy Grid view to display its structure.

Either way, analysis of the SOAP request template indicates that Google requires more details than just a simple search string! Of course, we could study the Web service documentation to explore all the parameters, but to make things easier we can just copy the snippet of XML code below (which we adapted from Google's request example) and paste it into XMLSpy's text view as indicated in the next screenshot. Then all that's needed is to edit in our own account key and search string. Let's search for Ansel Adams.

<key xsi:type="xsd:string">ENTER YOUR OWN ACCOUNT KEY HERE</key>
<q xsi:type="xsd:string">Ansel Adams</q>
<start xsi:type="xsd:int">0</start>
<maxResults xsi:type="xsd:int">10</maxResults>
<filter xsi:type="xsd:boolean">true</filter>
<restrict xsi:type="xsd:string"/>
<safeSearch xsi:type="xsd:boolean">true</safeSearch>
<lr xsi:type="xsd:string"/>
<ie xsi:type="xsd:string">latin1</ie>
<oe xsi:type="xsd:string">latin1</oe>

When we're satisfied with the parameters, we can send the request to the GoogleSearch Web service using the XMLSpy SOAP menu:

Did you ever ask a simple question and get back an answer that was much more complicated than you expected? Our request generates a SOAP response from Google's Web service that comes back in the form of a verbose XML document. XMLSpy automatically opens the response in a new window:

(Note the size and position of the handle in the scrollbar at the upper right. The complete response is 167 lines long.)

A few simple XSL commands can transform the interesting and relevant information from the response into HTML, which the XMLSpy Browser window will display as a Web page.

If you're following along, open a new XSLT stylesheet v 1.0 in XMLSpy and paste in the commands below:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes"/>
  <xsl:template match="/">
      <p>Your search took <xsl:value-of select="//searchTime"/> seconds</p>
      <p/>
      <p>Estimated total number of results: <xsl:value-of select="//estimatedTotalResultsCount"/>
      </p>
      <xsl:for-each select="//item">
        <xsl:call-template name="googleResult"/>
      </xsl:for-each>
    </xsl:template>
    <xsl:template name="googleResult">
    <p>
      <a>
        <xsl:attribute name="href"><xsl:value-of select="URL"/></xsl:attribute>
        <xsl:value-of select="title" disable-output-escaping="yes"/>
      </a>
    </p>
    <p>
      <xsl:value-of select="snippet" disable-output-escaping="yes"/>
    </p>
  </xsl:template>
</xsl:stylesheet>

These commands can be saved in an XSLT file for reuse. Then, with the response file in our active window, we can use the XSL/Query menu to assign the XSLT file to the data we received.

Once the XSLT file is assigned to the SOAP response file, clicking on the XMLSpy Browser tab performs the transformation and displays the HTML as it would appear in Internet Explorer.

You can even click the hyperlinks to open any of the Web sites in the XMLSpy Browser window. (If you do visit one of the sites, click the Back arrow in the XMLSpy Browser toolbar, or the Text tab to return to the response file.)

Later on, when you work on your own Web services projects, you will very likely want to perform similar transformations on SOAP responses to format or present the data in ways appropriate to your application.

If you're following along, you'll probably want to modify your search request and send it again. Each time you send your query to the Web service, you will receive a new response file. You can avoid going through the menu steps to assign the XSLT file to each new response by simply using Ctrl-C to copy the assignment code inserted at the top of the first response (usually at line 2), then paste it into that same location in each new response with Ctrl-V. But don't get carried away – the GoogleSearch Web service limits each account to 1,000 searches per day!

Here is an example of the code that assigns an XSLT file inside a response from GoogleSearch:

In summary, we just used XMLSpy to:

• Connect to a Web service
• Analyze the Web service's WSDL file to discover its operations
• Choose an operation and create a SOAP request
• Send the SOAP request to the Web service and receive a response
• Format the interesting parts of the response into a more useful form using XSLT

You can apply these same strategies to learn about other existing Web services, whether they are operated by other public-facing companies or developed by other project teams within your own organization. XMLSpy makes it easy.

The links below offer more information on the powerful Web services tools in Altova products:

• Learn more about the Web services features of XMLSpy® 2008 and MapForce® 2008
• View a Flash demo of the creation of Web services with XMLSpy and MapForce
• Read our Web services white paper, entitled Web services: Benefits, challenges, and a unique visual development solution
• Discover how we used the Altova solution to build a business operations Web service in this real-life case study
• Download a free 30-day trial of the Altova® MissionKit™ 2008

Google, eBay, Amazon, Yahoo! are trademarks or registered trademarks of their respective companies in the United States, other countries or both. Other company, product and service names may be trademarks or service marks of others.