One of the big benefits of ColdFusion MX (CFMX) is the ease with which it lets you build applications that consume Web services. 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.

More on ColdFusion Web services

For more information about building and consuming Web services with ColdFusion, check out these Builder.com articles:
“ColdFusion MX simplifies Web service calls and XML handling”
“Exposing Web services with ColdFusion MX”

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.

Results for a specific product
Amazon’s Web services API also supports making requests by ASIN, which is a unique identifier for each of the products Amazon sells. By passing a specific ASIN number to my details page and using that ASIN to request data from Amazon, as shown in Listing D, I can access a lot of information about that product. You can see that I have set the searchRequestType to heavy here, which means I’ll get more information back regarding this product than I would for the first request, which was set to lite.

The code in Listing D is similar to the previous Web service call. However, this time I’m passing in the ASIN from the first page through a URL variable. As you can see from Listing E, the output is also similar to the previous example (in Listing B), but this time, since I chose the heavy for the result type, I have more product data to work with.

For the example in Listing E, the details page displays a larger image for the item along with sales ranking and several customer reviews, data the lite request does not return. The API documentation explains all of the different types of data you have access to, which is pretty impressive. You can call up similar products, UPC codes, publishers, age groups, and track listings.

The entire range of Amazon products are available through its API, including DVDs, software, and, books. Amazon even supplies methods to let people add items to their Amazon shopping cart, wish lists, and even to purchase items. So as an affiliate, you could actually make some cash from your Web site

Additional request types you can use include searching by author and by Amazon-specific features like Listmania searches and wish lists. The code for invoking these other Web services is similar to the examples I provided above. You just need to check the documentation to determine what data a specific request needs and what format its results will be returned in.

We’re starting to see more useful Web services appear, and the pace is only going to accelerate. I hope these examples show how easily you can use ColdFusion MX to leverage Amazon’s Web services. When it comes to consuming Web services, CFMX’s simplicity puts ColdFusion developers in a position to greatly capitalize on this exciting new standard.