Working with Web Services

The previous section, on importing XML via a stylesheet, tells you more or less all you need to know to work effectively with Web services in FileMaker. The only other thing you need is a real Web service to work with.

It can actually be a bit difficult to find interesting Web services to play with. Many of the really meaty Web services, because they're providing useful information, charge an access or subscription fee of some kind. (These might include Web services that provide current weather information from satellites , or financial information, for example.) Many of the free Web services, by contrast, are either of limited scope, or else represent hobby work, student programming projects, and the like.

Happily, there are a few exceptions. We're going to take a look at Amazon.com's Web service offerings. Amazon, of course, has a user interface, presented via HTML, that you can use to conduct Amazon searches by pointing and clicking with your mouse in a Web browser. But Amazon has also been a pioneer in offering XML-based Web services that let you do the same thing, allowing you to integrate Amazon data into other applications.

Suppose you have a FileMaker database containing information about books. For each book you'd like to be able to check whether it's available from Amazon, and if so, at what price. With FileMaker's XML Import capability, you can do this fairly easily.

Accessing the Amazon Web Services

Working with Amazon's Web services is straightforward, but you need to do a couple of things first. You should visit http://www.amazon.com/ webservices ; there, you'll be able to download the Web services developer's kit, which provides useful documentation, and you'll also be able to apply for a "developer's token," which is a special personal key you'll need to send along with your Web service requests for validation. (There's no charge for either the developer's kit or the token.)

NOTE

If you don't want to take the trouble to apply for your own developer's token, you can use one that we requested for use in this book. That token is D1AT17BPIA1PX7.

Types of Web Services

As you browse the Internet looking for Web services, and as you look at the Amazon material, you may see a lot of references to different types of Web services, using terms such as SOAP or XML-RPC. Here's what you need to know about this: Though all the Web services we're interested in work by sending and receiving XML over an HTTP protocol, there are several different ways to do this. HTTP requests are divided into broad categories, called GET and POST. A GET request passes information in the URL: If you've ever seen a long, ugly-looking URL in your browser, like http://my.ecommerce-site.com/cartApp.astj?userID=ED45jUiJJ&sessKey=6a45Rtfe4, you're looking at information being sent via a GET request. On the other hand, if you've ever filled out an HTML form and pressed the Submit button, odds are the data were being sent behind the scenes, in what's called a POST request.

Web services may work with either GET or POST requests. FileMaker's XML Import feature, however, can make only a GET request. But a number of the most common Web services techniques work exclusively via POST.

SOAP is an example of such a Web services protocol. SOAP transactions send a complex XML request to the server via a POST operation. Many Web services are available only via SOAP. A good example is the Google Web service, which lets you interface directly to the Google search engine. Because Google is SOAP-based, there is no direct way for FileMaker to interact with the Google Web service at the moment.

In looking for FileMaker-ready Web services, then you're looking for Web services that support simple XML over HTTP via GET requests.

The developer's kit comes with documentation that shows how to formulate various types of HTTP requests for data. Here's an example URL:

 http://xml.amazon.com/onca/xml3?t=xxx&dev-t= D1AT17BPIA1PX7 &PowerSearch=title:Genet&mode=books&type=lite&page=1&f=xml 

This searches Amazon for books with the word "Genet" in the title. Try entering the above URL in Internet Explorer 5 or greater (which renders the resulting XML nicely ), and you'll see what the returned results look like. This returns data in Amazon's "lite" format, which has less information than the corresponding "heavy" format.

Amazon's XML formats, whether "lite" or heavy, are clearly not FileMaker's FMPXMLRESULT . So if you want to bring this book data back into FileMaker via an XML import, you need a stylesheet to transform it appropriately on the way in.

Writing a Stylesheet to Import Amazon Data

Let's say we have a book database with the field structure shown in Figure 22.8.

Figure 22.8. Field structure for a database of book information.

We can bring Amazon data into this FileMaker structure by performing an import from an XML data source, and applying a stylesheet to the inbound data. The stylesheet looks and works a lot like the one in Listing 22.8. We show it here, for completeness, as Listing 22.9.

Listing 22.9. Stylesheet for Transforming Amazon XML into FMPXMLRESULT XML

 <?xml version="1.0" encoding="UTF-8" ?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">   <xsl:output indent="yes" method="xml"/>   <xsl:template match="ProductInfo">     <FMPXMLRESULT xmlns="http://www.filemaker.com/fmpxmlresult">       <ERRORCODE>0</ERRORCODE>       <PRODUCT BUILD="11-05-2003" NAME="FileMaker Pro" VERSION="7.0v1"/>       <DATABASE DATEFORMAT="M/d/yyyy" LAYOUT="" NAME="Student.fp7" RECORDS="10"  TIMEFORMAT="h:mm:ss a"/>       <METADATA>         <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Title" TYPE="TEXT"/>         <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Publisher" TYPE="TEXT"/>         <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="ISBN" TYPE="TEXT"/>         <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="AmazonURL" TYPE="TEXT"/>         <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="ListPrice" TYPE="NUMBER"/>         <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="OurPrice" TYPE="NUMBER"/>         <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="UsedPrice" TYPE="NUMBER"/>         <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Authors" TYPE="TEXT"/>       </METADATA>       <RESULTSET FOUND="10">         <xsl:for-each select="Details">           <ROW MOD RECORD>             <COL>               <DATA>                 <xsl:value-of select="ProductName"/>               </DATA>             </COL>             <COL>               <DATA>                 <xsl:value-of select="Manufacturer"/>               </DATA>             </COL>             <COL>               <DATA>                 <xsl:value-of select="Asin"/>               </DATA>             </COL>             <COL>               <DATA>                 <xsl:value-of select="url"/>               </DATA>             </COL>             <COL>               <DATA>                 <xsl:value-of select="ListPrice"/>               </DATA>             </COL>             <COL>               <DATA>                 <xsl:value-of select="OurPrice"/>               </DATA>             </COL>             <COL>               <DATA>                 <xsl:value-of select="UsedPrice"/>               </DATA>             </COL>             <COL>               <DATA>                 <xsl:for-each select="Authors/Author">                   <xsl:value-of select="."/>                   <xsl:if test="position() != last()">                     <xsl:text>, </xsl:text>                   </xsl:if>                 </xsl:for-each>               </DATA>             </COL>           </ROW>         </xsl:for-each>       </RESULTSET>     </FMPXMLRESULT>   </xsl:template> </xsl:stylesheet> 

This is extremely similar to the earlier stylesheet, even down to the treatment of book authors, which occur in nested groups: Here, we loop over authors in the same way we looped over parent records, flattening them into a single text field.

Building a More Flexible Interface to a Web Service

The previous section concentrated on the stylesheet that you would use to import data from Amazon. But so far, we've just assumed FileMaker is issuing some hard-coded URL to perform an Amazon search. In fact, we probably want our users to be able to compose their own queries and submit them to Amazon.

There's no great mystery to this. The Amazon developer's kit documents the different types of search strings that the Amazon Web service can accept. (If we're just searching for books, a lot of the more interesting options can be found as part of the overall "power search" option.)

So far, we've imported XML only from data sources we specified via a hard-coded URL. It's also possible, though, when importing XML into FileMaker via a script, to draw the XML from a data source specified by a calculation. Figure 22.9 shows the relevant dialog choice.

Figure 22.9. When importing XML into FileMaker via a script, you can use a calculation to create the source URL on the fly.

This makes it possible to compose the Amazon URL on the fly based on user input. For example, if we wanted to search for books by Naguib Mafouz, published by (say) Farrar Straus & Giroux, the Amazon URL would look like this:

 http://xml.amazon.com/onca/xml3?t=xxx&dev-t=D1AT17BPIA1PX7&PowerSearch=author:Mafouz and  publisher:giroux&mode=books &type=lite&page=1&f=xml 

(In the real URL, you would use your Seller ID, if you had one instead of the nonsense string xxx .) To compose this URL dynamically, you'd need to offer the user a couple of global fields to type into. Assume the user called gAuthorSearch and gPublisherSearch . You could then define a calculation field that would look something like this:

 http://xml.amazon.com/onca/xml3?t=xxx&dev-t=D1AT17BPIA1PX7 &PowerSearch=author:" &  gAuthorSearch & " and publisher:" & gPublisherSearch & "&mode=books&type=lite&page=1&f=xml" 

And, as shown in Figure 22.9, you can instruct FileMaker to derive the URL from a calculation, which could point directly to this dynamic field. This snippet is really useful only as an example of how you might go about this conceptually. In reality, you'd need to do some work to build a really nice interface to Amazon. You'd want to add fields for all the types of Amazon searches (there are about seven). You'd also want to provide for the fact that the user might choose to search on some but not all criteria, making it a good idea to omit the unused search types from the URL. You'd have to account for the fact that it's possible for searches to have multiple words, in which case they need to be enclosed in quotes. And you'd want to account for the different search types Amazon allows, such as searching by exact match or initial match.