ColdFusion: Make Yahoo! Web Service REST Calls

ColdFusion makes it simple to make Yahoo! Web Services REST requests. In this HOWTO, we discuss how the CFHTTP tag can be used along with recommended ways to use the tag. This page contains these sections:

Overview of Making REST Requests With ColdFusion

REST requests are modeled after the way a web browser makes requests from a web server. So, when we use the ColdFusion programming language for REST requests, our ColdFusion scripts mimic the way a web browser interacts with a web server.

ColdFusion's CFHTTP tag allows for both GET and POST requests. Most Yahoo! Web Services REST requests mimic HTTP GET requests, but a few use HTTP POST, so, in this HOWTO, we provide sample code for both HTTP GET and HTTP POST requests when applicable.

Yahoo! Web services return XML data. Some also can optionally return JSON and Serialized PHP data. For information about the various Yahoo! Web Services, see the documentation at the Yahoo! Developer Network. The documentation on Constructing REST Requests can help you put together the parameters for a Yahoo! Web Services request if you are unfamiliar with REST syntax.

For example, here's a request from Yahoo! Search web search service for the keyword "persimmon" that returns ten results:

http://api.search.yahoo.com/ WebSearchService /V1/webSearch?appid=YahooDemo &query=persimmon&results=10

By default the Yahoo! Web Services return XML output. With the output=json parameter, you can get JSON output instead:

http://api.search.yahoo.com/ WebSearchService /V1/webSearch?appid=YahooDemo &query=persimmon&results=10 &output=json

Prequisites

There are no prequisites for working with ColdFusion and Yahoo!'s web services since CFHTTP is built into the language.

Making Requests With CFHTTP

The CFHTTP tag is used for making network requests from a high-level programming language. It greatly simplifies the code necessary to do HTTP GET and POSTs and offers developers a lot of network connection options.

GET Requests With CFHTTP

Making network requests using CFHTTP is very simple. All you need is a URL:

<cfhttp url="http://api.search.yahoo.com/ImageSearchService/V1/imageSearch?appid=YahooDemo&query=#urlEncodedFormat('Al Gore')#&results=8" charset="utf-8">

The response is returned in a variable named CFHTTP. This variable is a structure with various keys, one of which is the FileContent key containing the returned data.
A complete code sample is available here.

POST Requests With CFHTTP

Achieving POST requests with CFHTTP is slightly more complicated than doing GET because additional request parameters must be sent along with the request URL. To illustrate, we use the Content Analysis web service which requires that you use HTTP POSTs for your requests.

<cfset theURL = "http://search.yahooapis.com/ContentAnalysisService/V1/termExtraction">
<cfhttp url="#theURL#" charset="utf-8" method="post">
<cfhttpparam type="formfield" name="appid" value="YahooDemo">
<cfhttpparam type="formfield" name="context" value="Italian sculptors and painters of the renaissance favored the Virgin Mary for inspiration">
<cfhttpparam type="formfield" name="query" value="madonna">
</cfhttp>

As with the previous example, the result is returned in a CFHTTP variable.

A complete code sample is available here.

Error Handling

Yahoo offers many REST web services but they don't all use the same error handling. That's because some of Yahoo!'s Web Services came from companies that Yahoo! acquired, such as Flickr and Upcoming. These companies already had their own web services error handling in place. However, most web services that we developed in-house, including all of our Yahoo! Search Web Services, use the documented error handling.

The documented error handling returns error information using the HTTP status code returned in the HTTP response header.

Using CFHTTP

The HTTP status code is available via CFHTTP.responseHeader.status_code.

The code is interpreted based on the documented error handling:

<cfswitch expression="#cfhttp.responseHeader.status_code#">

<cfcase value="503">
<cfthrow message="Your call to Yahoo Web Services failed and returned an HTTP status of 503. That means: Service unavailable. An internal problem prevented us from returning data to you.">
</cfcase>

<cfcase value="403">
<cfthrow message="Your call to Yahoo Web Services failed and returned an HTTP status of 403. That means: Forbidden. You do not have permission to access this resource, or are over your rate limit.">
</cfcase>

<cfcase value="400">
<cfthrow message="Your call to Yahoo Web Services failed and returned an HTTP status of 400. That means: Bad request. The parameters passed to the service did not match as expected. The exact error is returned in the XML response.">
</cfcase>

<cfcase value="200">
<!--- Good response, do nothing. --->
</cfcase>

<cfdefaultcase>
<cfthrow message="Your call to Yahoo Web Services returned an unexpected HTTP status of: #cfhttp.responseHeader.status_code#">
</cfdefaultcase>

</cfswitch>

A complete code sample is available here.

For More Information

For more information on using ColdFusion with Yahoo! Web Services APIs, see The Yahoo! Developer Network ColdFusion Developer Center.