SOAP Web services with ColdFusion MX

As the Web services hype dies down and real applications creep in, CFMX’s ease of use makes it a compelling development option. Here, I’ll demonstrate just how easy CFMX makes it to invoke Web services by showing you how to query and return data from Amazon.com’s recently introduced Web services interface.

Before you start, you’ll need to head over to the Amazon Web Services page, download the development kit, and get your development token (a.k.a. your ID number). You’ll send this token when you invoke Amazon’s Web services, and it is one of the ways Amazon can identify your site as an affiliate and pay you for sales referrals. Getting the token is free, and so is signing up to become an affiliate, if you wish. For this example, all you’ll need is the development key.

Performing a keyword search
To start, I’d like to query Amazon.com with some search terms and display the results. The developer’s kit documentation has a section that explains what format a search request should be in and also describes the structure of the response. There are two important points to consider here.

First, the docs say that for the request method KeywordSearchRequest, there are several values that must be provided. These are: keyword, page, mode, tag, type, sort, and devtag. Descriptions of these variables are given in the docs. At first glance, you might think that you would invoke the Amazon Web service and pass it arguments for each of these values, as in the code in Listing A.

But that's not the way it works. It took a bit of digging around and experimenting, but I finally figured out the solution: Amazon wants you to pass only one variable, keyWordSearchRequest, which contains an array or structure of the required values. So the correct approach would be first to build your search request structure, and then pass that populated structure to Amazon as an argument. Listing B contains working code illustrating how to do this by searching Amazon for a list of all music products matching the keyword "underworld."

You might notice that my search request contained the parameter searchRequestType, which I set to lite. This tells Amazon that I want light (as opposed to heavy) search results, which contain only basic product information and therefore are returned faster.

Once you’ve formatted the request successfully, it returns an array of products that matched the keyword, searchResults in Listing B. Each array item contains data on that product, and displaying it to the user is quite straightforward, as shown in Listing C.

You get a lot of product information back from such a request, and the documentation describes it thoroughly. In the example above, I looped over the array of products and output a small image (getImageUrlSmall), the product name (getProductName), the name of the artist (getArtists), and finally its price (getListPrice).

You can also see that I made the product name a link to a product details page for that item. The Amazon.com data for each object contains a link back to Amazon’s item details page on its Web site, so I could have just used that link. But maybe I don’t want to hand off this customer to Amazon just yet; maybe I want to keep him or her on my site for just a bit longer. To do that, I could create a second page that displays some of the item’s details.