Blogging has become a huge phenomenon over the past several years, and blogs can be found in both the private and professional sectors. In fact, the line between personal and professional blogs, especially concerning technology, has blurred. After all, most of us cannot help but write about and experiment with technology even when it is on our own time.

Larger blog sites and operations have begun to see a real demand for services that allow developers to access the blogging system’s content and controls programmatically from within other applications. This has also led to the pleasant side effect of third-party tools being developed for programmatic remote access to blog systems.

These APIs range from direct access of management tools for blogging software to simple searching of blog content, and everything in between. In this section, I will list some of the more popular APIs of these blogging web services and discuss their functionality so that you will know what blog tools are available to you.

The following is a list of some of the more popular blogging APIs:

A good example of using a blogging service API in an application is FeedBurner’s Feed Management API, also known as MgmtAPI on the FeedBurner site. The MgmtAPI enables FeedBurner publishers to create and manage their accounts programmatically and can facilitate the following functions: find, get, add, modify, delete, and resync. This capability can be useful on its own or combined with other web services to create a mashup (see Chapter 19). All of these blog APIs may not work in the same way, but they are all fairly easy to use.

For a simple example, we will look at the MgmtAPI Find Feeds functionality. MgmtAPI uses the REST protocol for all its functionality, and returns XML for its response. The Request URL looks like this:

http://api.feedburner.com/management/1.0/FindFeeds?user=[username]&
password=[password]

This method has no parameters associated with it, other than the standard authentication parameters, and it simply returns a list of all the feeds associated with the user.

The response XML has a schema document located at http://api.feedburner.com/management/1.0/FindFeedsResponse.xsd. Basically, five fields are returned with the response, as shown in Table 18-1.

A sample response for a Find Feeds request would look something like this:

<?xml version="1.0" encoding="utf-8" ?>
<feeds>
    <feed id="6" uri="trey-rants" title="Where Are the Standards?" />
    <feed id="26" uri="trey" title="Using OpenOffice as Your Word Processor" />
    <feed id="1999" uri="trey-sarah" title="Latest with the Twins" />
</feeds>

No server-specific errors were associated with this request. If the user passed to the server does not have any feeds, the feeds element in this simply has no children.

Example 18-1 shows the basics of how to call this request within PHP and handle the results. Unlike in the REST call we made in Example 17-6 in Chapter 17, in this example we use the PEAR library HTTP:Request for better error handling of the response. You can do what you want with the response, as we’ve discussed in detail throughout Part II of this book.

<?php
/**
 * Example 18-1. Calling the FeedBurner MgmtAPI's Find Feeds method using PHP.
 *
 * This file is just a simple example of fetching data using REST and parsing
 * the results.  Much more could be done on the server side, especially if part
 * of a mashup, in this script.
 */

/**
 * The file, user.inc, contains the username and password for the REST request.
 */
require_once('user.inc'),
/**
 * This is the PEAR HTTP:Request library used to make our request.
 */
require_once('HTTP/Request.php'),

/* Set up the request */
$request =& new HTTP_Request("http://api.feedburner.com/management/"
    ."1.0/FindFeeds?user=$username&password=$password");
$request->addHeader('Accept', 'application/atom+xml'),

/* Get the results of the request */
$results = $request->sendRequest( );

/* Begin the response text */
$response = '<?xml version="1.0" encoding="utf-8"?>';

/* Was there a problem with the request? */
if (PEAR::isError($results))
    $response .= '<response code="500">'.$response->getMessage( ).'</response>';
else {
    $code = $request->getResponseCode( );
    $response .= '<response code="'.$code.'">';
    $xml = new SimpleXMLElement($results);

    /* We can check for whatever codes we want here */
    switch ($code) {
        case 200:
            /* Were there any feeds? */
            if ($xml->children( )) {
                $response .= '<feeds>';
                /* Loop through the feeds */
                foreach ($xml->children( ) as $feed) {
                    $response .= '<feed>';
                    $response .= "<title>{$feed['title']}</title>";
                    $response .= "<link>{$feed['uri']}</link>";
                    $response .= '</feed>';
                }
                $response .= '</feeds>';
            } else
                $response .= '<feeds />';
            break;
        default:
            $response .= '<feeds />';
            break;
    }
    $response .= '</response>';
}
/*
 * Change the header to text/xml so that the client can use the return string
 * as XML
 */
header('Content-Type: text/xml'),
/* Give the client the XML */
print($response);
?>

Bookmarking, at least in terms of the sites that offer it, is the ability to track and share (by category) saved bookmarks with others around the world. The del.icio.us service has made bookmarking popular, as the del.icio.us web site is by far one of the most popular when it comes to blogging, photo and video sharing, and so on.

Here are some of the well-known web service APIs that are available:

These web service APIs are easy enough to use, but because of its popularity, I’ll show a little more of the del.icio.us API. del.icio.us uses REST over HTTPS for all of its API calls, so a username and password are required just as they were in Example 18-1. The REST URI for adding a post to del.icio.us programmatically is:

https://api.del.icio.us/v1/posts/add?

You can add to this request a couple of required parameters, plus several more optional ones. Table 18-2 lists these parameters.

CCYY-MM-DDThh:mm:ssZ

For a successful post, the server will respond as follows:

<result code="done" />

If the post failed, however, the response will be:

<result code="something went wrong" />

Using PHP on the server, Example 18-2 shows how an Add request can be executed with PEAR and the response captured to notify the client. This example assumes that the information to post is coming from a POST from the client.

<?php
/**
 * Example 18-2. Adding a post programmatically to del.icio.us using PHP.
 *
 * This file demonstrates how to take the form post from the client and post
 * this data to del.icio.us using a REST architecture.  The result from the
 * post is sent back to the client.
 */


/**
 * The file, user.inc, contains the username and password for the REST request.
 */
require_once('user.inc'),
/**
 * This is the PEAR HTTP:Request library used to make our request.
 */
require_once('HTTP/Request.php'),

/* Is there something to post? */
if (!isempty($_REQUEST['description']) && !isempty($_REQUEST['url'])) {
    /* Set up the request */
    $request =& new HTTP_Request("https://$username:[email protected]/v1"
        ."/posts/add?url=".$_REQUEST['url']. "&description="
        .$_REQUEST['description']);
    $request->addHeader('Accept', 'application/atom+xml'),

    /* Get the results of the request */
    $results = $request->sendRequest( );

    /* Begin the response text */
    $response = '<?xml version="1.0" encoding="utf-8"?>';

    /* Was there a problem with the request? */
    if (PEAR::isError($results))
        $response .= '<response code="500">'.$response->getMessage( ).'</response>';
    else {
        $code = $request->getResponseCode( );
        $response .= '<response code="'.$code.'">';
        $xml = new SimpleXMLElement($results);
        $response .= $xml['code'];
        $response .= '</response>';
    }
} else
    $response .= '<response code="500">There was nothing to post.</response>';
/*
 * Change the header to text/xml so that the client can use the return string
 * as XML
 */
header('Content-Type: text/xml'),
/* Give the client the XML */
print($response);
?>

Financial institutions are beginning to see the advantages of having a web service attached to their financial information. Most services are offered at a price, as these types of services are more useful to a corporation or business than to an individual. Examples of services being offered today are those that involve the various stock markets, accounting control to an application, invoicing, credit checking, mutual fund prices, and currency rates.

A sample of some of these web services follows:

These services give you everything you need to start adding financial web service data into your own Ajax applications without much work. The only real downside with financial services is that they all charge fees for usage, but if you can justify those costs, the benefits of adding this kind of data can be enormous.

One of the hottest topics for application development is in the realm of web mapping. This subject, more commonly referred to as Geographic Information Systems (GIS) within the industry, has some promising applications. This is especially true when used in a mashup with other available data sets.

Most people are visual by nature; as such, using maps to help convey a stat or fact adds good value to an application. For example, is it easier to get a list of addresses for restaurants in a district of a city you are unfamiliar with, or to get a map with the locations marked on it? Think about what started with MapQuest and driving directions, and is now a commonplace and expected function of these types of sites—a map marking the route with supplementary text giving step-by-step directions. This kind of visual aid is what web mapping is all about. Having access to mapping service APIs opens the door for developers to create many new and useful tools.

Many mapping services are available; here we will look at several of the bigger players so that you can get an idea of what they offer. A sample of the API, and of course, something visual, will accompany the list of mapping services. Here is this list:

Yahoo! makes it easy to use its mapping API to create custom maps and embed them into an existing application. After obtaining an application ID from Yahoo!, using the Yahoo! Maps AJAX API library is a snap. The first thing to do is to include the library into your application, like so:

<script type="text/javascript"
    src="http://api.maps.yahoo.com/ajaxymap?v=3.0&appid=[Application Id]">
</script>

Once you have the library, you just create a placeholder element for the map that you can shape with CSS rules into whatever size you need. After that, simply decide whether to use latitude and longitude coordinates to specify the starting map location, or the built-in geocoding feature. Example 18-3 shows how to add a simple map control to an application that has some elementary tools included with it.

<html>
    <head>
        <script type="text/javascript"
            src="http://api.maps.yahoo.com/ajaxymap?v=3.0&appid=[Application Id]">
        </script>
        <style type="text/css">
            #mapContainer {
                height: 600px;
                width: 600px;
            }
        </style>
    </head>
    <body>
        <div id="mapContainer"></div>
        <script type="text/javascript">
            //<![CDATA[
            /* Create a latitude/longitude object */
            var myPoint = new YGeoPoint(38.64, -90.24);
            /* Create a map object */
            var map = new YMap(document.getElementById('mapContainer'));

            /* Add a map type control */
            map.addTypeControl( );
            /*
             * Set the map type to one of: YAHOO_MAP_SAT, YAHOO_MAP_HYB, or
             * YAHOO_MAP_REG
             */
            map.setMapType(YAHOO_MAP_REG);
            /* Add a pan control */
            map.addPanControl( );
            /* Add a slider zoom control */
            map.addZoomLong( );
            /* Display the map centered on a latitude and longitude */
            map.drawZoomAndCenter(myPoint, 3);
            //]]>
        </script>
    </body>
</html>

Figure 18-1 shows what this code would produce in the application. Its main features are the panning and zooming tools, and the ability to toggle among satellite, map, and hybrid modes.

Figure 18-1. The result of putting a Yahoo! Map control into a web page

A good addition to this type of map is the ability to add features that contain notations without having to know any extra programming. By having your script pass GeoRSS tagged files through the API interface, Yahoo! Maps will automatically add these features to the map. The World Wide Web Consortium (W3C) has a basic Geo (WGS84 lat/long) Vocabulary for defining these XML-based files, of which Yahoo! Maps takes advantage in RSS 2.0 format. You can find more information on this vocabulary at http://esw.w3.org/topic/GeoInfo. Yahoo! Maps bases its XML file on the GeoRSS 2.0 standard, and uses channel and item elements to define the data. Example 18-4 shows an example of a GeoRSS feed.

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
        xmlns:ymaps="http://api.maps.yahoo.com/Maps/V2/AnnotatedMaps.xsd">
    <channel>
        <title>Example RSS Data</title>
        <link><![CDATA[http://www.oreilly.com]]></link>
        <description>Sample result</description>
        <ymaps:Groups>
            <Group>
                <Title>Museums</Title>
                <Id>museums</Id>
                <BaseIcon width="16" height="16">
                    <![CDATA[http://developer.yahoo.com/maps/star_blue.gif]]>
                </BaseIcon>
            </Group>
            <Group>
                <Title>Parks</Title>
                <Id>parks</Id>
                <BaseIcon width="16" height="16">
                    <![CDATA[http://developer.yahoo.com/maps/star_green.gif]]>
                </BaseIcon>
            </Group>
        </ymaps:Groups>
        <item>
            <title>St. Louis Art Museum</title>
            <link><![CDATA[http://www.stlouis.art.museum/]]></link>
            <description>The St. Louis Art Museum</description>
            <ymaps:Address>1 Fine Arts Drive</ymaps:Address>
            <ymaps:CityState>St. Louis, MO</ymaps:CityState>
            <ymaps:GroupId>museums</ymaps:GroupId>
        </item>
        <item>
            <title>Missouri History Museum</title>
            <link>
                <![CDATA[
                    http://www.mohistory.org/content/HomePage/HomePage.aspx
                ]]>
            </link>
            <description>The Missouri History Museum</description>
            <ymaps:Address>5700 Lindell Blvd</ymaps:Address>
            <ymaps:CityState>St. Louis, MO</ymaps:CityState>
            <ymaps:GroupId>museums</ymaps:GroupId>
        </item>
        <item>
            <title>City Museum</title>
            <link><![CDATA[http://www.citymuseum.org/home.asp]]></link>
            <description>City Museum</description>
            <ymaps:Address>701 N 15th St</ymaps:Address>
            <ymaps:CityState>St. Louis, MO</ymaps:CityState>
            <ymaps:GroupId>museums</ymaps:GroupId>
        </item>

        <item>
            <title>Forest Park</title>
            <link><![CDATA[http://www.forestparkforever.org/HTML/]]></link>
            <description>Forest Park Forever</description>
            <ymaps:Address>5595 Grand Dr</ymaps:Address>
            <ymaps:CityState>St. Louis, MO</ymaps:CityState>
            <ymaps:GroupId>parks</ymaps:GroupId>
        </item>
        <item>
            <title>Tower Grove Park</title>
            <link>
                <![CDATA[http://stlouis.missouri.org/parks/tower-grove/]]>
            </link>
            <description>Tower Grove Park</description>
            <ymaps:Address>4256 Magnolia Ave</ymaps:Address>
            <ymaps:CityState>St. Louis, MO</ymaps:CityState>
            <ymaps:GroupId>parks</ymaps:GroupId>
        </item>
    </channel>
</rss>

To include this type of data in a map, simply add the following code to the JavaScript:

/* The sample overlay data from a GeoRSS file */
map.addOverlay(new YGeoRSS('http://www.holdener.com/maps/sample.xml'));

This is just a simple example of using the Yahoo! Maps API. Other map service APIs are similar in their ease of use, though they differ from each other in one way or another. Such a variety of mapping service APIs is available that it should not be too difficult to find one that meets your needs.

Many music and video capabilities are available on the Web today, from streaming video to Internet radio stations. In fact, so many exist that it is hard to even begin to list the choices available for developers in the form of web services. Both the business and private sectors have come to realize how effective music and video media on the Web can be. And not just for personal enjoyment, either, but also for sharing homemade or favorite sources of this media with the rest of the world.

Services such as YouTube were instant successes, and they have become a major source of community sharing for the world in the medium of streaming video. YouTube is so successful that a number of similar services made for a specific purpose are now thriving on the Web. Because of this popularity, it was only natural for a number of web services to be created that aid in the use and functionality of these sites.

Here are a select few of these services:

As I mentioned earlier, a popular service on the Internet is the video sharing community of YouTube. Thanks to services such as this, users can easily search and view videos that are tagged by category from within other applications. There are no tricks to adding the functionality of YouTube and similar services, as they all provide fairly easy-to-use APIs for this purpose.

YouTube has both REST and XML-RPC access to its web service, though the following examples use REST. The service is easy to access and use, as it takes the following format to request data:

http://www.youtube.com/api2_rest?method=<method name>&dev_id=<developer id>
[&user=<YouTube user name>]

A successful response to this REST request takes the following format:

<ut_response status="ok">
    <!-- The XML for the response -->
<ut_response>

A request that ends in error, however, takes this form:

<ut_response status="fail">
    <error>
        <code>Code Number</code>
        <description>Description of code error.</description>
    </error>
</ut_response>

The following list shows the different errors that YouTube can return when a problem occurs:

YouTube gives developers access to many requests—some dealing with user access and others dealing with video viewing. Table 18-3 lists these different methods and summarizes their usage.

With the youtube.videos.list_featured method as an example, a request to the service would look like this:

http://www.youtube.com/api2_rest?method=youtube.videos.list_featured&
dev_id=<developer id>

The response for this request looks like this:

 <video_list>
    <video>
        <author>macpulenta</author>
        <id>y14g50q4hQ0</id>
        <title>Scarlett Johansson - Speed Painting</title>
        <length_seconds>412</length_seconds>
        <rating_avg>4.5</rating_avg>
        <rating_count>4476</rating_count>
        <description>
            A new speed painting in Photoshop. At this time, a beautiful woman...
            Enjoy it.  And thanks for all your comments and messages to my other
            videos!! Gracias!!!

            (It was done with a digital tablet and the Background music is
            "Adagio for strings" by Dj Tiesto)
        </description>
        <view_count>859395</view_count>
        <upload_time>1121398533</upload_time>
        <comment_count>1883</comment_count>
        <tags>scarlett johansson speed painting photoshop</tags>
        <url>http://www.youtube.com/watch?v=y14g50q4hQ0</url>
        <thumbnail_url>
            http://static.youtube.com/get_still?video_id=y14g50q4hQ0
        </thumbnail_url>
        <embed_status>ok</embed_status>
    </video>
    .
    .
    .
</video_list>

This response can be sent from a server-side script directly to a client script that requested it with an Ajax call. Then it is necessary to parse the information needed for the particular client page so that it can be displayed. Let’s assume that the JavaScript code will be placing the data in an XHTML structure like this:

<div class="youTubeContainer">
    <div class="youTubeTitle"></div>
    <div class="youTubeThumb">
        <a href="">
            <img src="" alt="" title="" />
        </a>
    </div>
    <div class="youTubeDescription"></div>
</div>

Example 18-5 shows the JavaScript that handles the response from the server script and parses it to create the YouTube links in the application.

/*
 * Example 18-5. Parsing a response from YouTube and putting the results into an
 * XHTML application.
 */

/**
 * This function, getYouTubeResults, takes the /xhrResponse/'s responseXML and
 * parses it, placing the necessary elements into the output string that will be
 * the /innerHTML/ of /someElement/.
 *
 * @param {Object} p_xhrResponse The XMLHttpRequest response from the server.
 * @return Returns whether the results were obtained correctly.
 * @type Boolean
 */
function getYouTubeResults(p_xhrResponse) {
    try {
        /* Get all of the video elements from the response */
        var videos = p_xhrResponse.responseXML.getElementsByTagName('video'),
        var output = '';

        /* Loop through the video elements and format the output */
        for (var i = 0, il = videos.length; i < il; i++) {
            output += '<div class="youTubeContainer">';
            output +=
                '<div class="youTubeTitle">' +
                videos[i].getElementsByTagName('title')[0].nodeValue +
                '</div>';
            output +=
                '<div class="youTubeThumb"><a href="' +
                videos[i].getElementsByTagName('url')[0].nodeValue +
                '"><img src="' +
                videos[i].getElementsByTagName('thumbnail_url')[0].nodeValue +
                '" alt="' + videos[i].getElementsByTagName('title')[0].nodeValue +
                '" title="' + videos[i].getElementsByTagName('title')[0].nodeValue +
                '" /></a></div>';
            output +=
                '<div class="youTubeDescription">' +
                videos[i].getElementsByTagName('description')[0].nodeValue +
                '</div>';
            output += '</div>';
        }
        /* Place the output in the document */
        $('someElement').innerHTML = output;
        /* Return true, indicating the function executed correctly */
        return (true);
    } catch (ex) {
        /*
         * There was a problem retrieving video, let the user know and return
         * false
         */
        $('someElement').innerHTML =
            'There was an error getting the YouTube videos.';
        return (false);
    }
}

Being a news junkie, it is important to me to get as much news information as I can as quickly as I can. Unfortunately, there has never been one site that gives me everything I want to use. As the number and variety of news services and RSS feeds have increased, however, so has the ability to create my own news sites that aggregate everything I want to view together at one time.

Some services supply news directly from their sites and provide that data through their own services. And other services grab different RSS feeds and provide a single point at which a variety of news can be obtained.

The following are some examples of news services:

I’ll use the NewsIsFree service for our news and weather services examples. NewsIsFree uses a SOAP interface for all communication to its web service. To use this service, the developer must have a valid username and password, plus a personal application key.

It is simple to create a request to NewsIsFree using PHP and SOAP. First, create a client connection using PHP 5’s built-in SOAP class, SoapClient( ):

$client = new SoapClient('http://newsisfree.com/nifapi.wsdl',
    array('trace' => 1, 'exception' => 0));

Then, simply call the API method with the necessary parameters. For example, to call the API method getNews( ), you would code the following:

$result = $client->getNews('[application key]',
                           '[login]',
                           '[password]',
                           '[site id]',
                           true);

Table 18-4 lists all of the API functions that are available for use with the NewsIsFree web service.

For a getNews( ) request, the results are passed as an RSS feed, and they look like this:

<?xml version="1.0" encoding="UTF-8"?>
<rss version="0.92">
    <channel>
        <title>CNN</title>
        <link>/sources/info/2315/</link>
        <description>
            The world's news leader (powered by
            http://www.newsisfree.com/syndicate.php - FOR PERSONAL AND NON
            COMMERCIAL USE ONLY!)
        </description>
        <language>en</language><webMaster>[email protected]</webMaster>
        <lastBuildDate>05/03/07 02:59 7200</lastBuildDate>
        <image>
            <link>http://www.newsisfree.com/sources/info/2315/</link>
            <url>http://www.newsisfree.com/HPE/Images/button.gif</url>
            <width>88</width>
            <height>31</height>
            <title>Powered by NewsIsFree</title>
        </image>
        <item>
            <id>i,199624023,2315</id>
            <title>Armored truck robbers flee with $1.8 million</title>
            <link>
                http://rss.cnn.com/˜r/rss/cnn_topstories/˜3/113743933/index.html
            </link>
            <description>
                Read full story for latest details.&lt;p&gt;&lt;a
                href="http://rss.cnn.com/˜a/rss/cnn_topstories?a=rX51Ch"&gt;
                &lt;img id="hpeitemad"
                src="http://rss.cnn.com/˜a/rss/cnn_topstories?i=rX51Ch"
                border="0"&gt;&lt;/img&gt;&lt;/a&gt;&lt;/p&gt;
                &lt;img src="http://rss.cnn.com/˜r/rss/cnn_topstories/˜4/113743933"
                height="1" width="1"/&gt;
            </description>
            <read>0</read>
        </item>
        .
        .
        .
        <item>
            <id>i,199609740,2315</id>
            <title>Dow on best streak since 1955</title>
            <link>
                http://rss.cnn.com/˜r/rss/cnn_topstories/˜3/113721652/index.htm
            </link>
            <description>
                The Dow Jones industrial average hit another record high Wednesday,
                capping its longest winning stretch in almost 52 years as investors
                welcomed strong earnings, lower oil prices, media merger news and a
                strong reading on manufacturing.&lt;p&gt;
                &lt;a href="http://rss.cnn.com/˜a/rss/cnn_topstories?a=bodxMF"&gt;
                &lt;img id="hpeitemad"
                src="http://rss.cnn.com/˜a/rss/cnn_topstories?i=bodxMF"
                border="0"&gt;&lt;/img&gt;&lt;/a&gt;&lt;/p&gt;&lt;img
                src="http://rss.cnn.com/˜r/rss/cnn_topstories/˜4/113721652"
                height="1" width="1"/&gt;
            </description>
            <read>0</read>
        </item>
    </channel>
</rss>

Example 18-6 shows how to construct a request to NewsIsFree for the latest CNN news. The results are passed to the client as XML to be parsed and displayed to the user.

<?php
/**
 * Example 18-6. Demonstrating how to use SOAP and PHP to pull data from the
 * NewsIsFree web service.
 *
 * This example uses PHP 5's built-in SOAP class to request information from the
 * NewsIsFree web service.
 */

/* Set the parameters for the request query */
$app_key = '[application id]';
$login = '[login]';
$password = '[password]';
/* Site id 2315 is CNN */
$site = '2315';

$client = new SoapClient('http://newsisfree.com/nifapi.wsdl'),
try {
    $result = $client->getNews($app_key, $login, $password, $site, true);
    /*
     * Change the header to text/xml so that the client can use the return string
     * as XML
     */
    header('Content-Type: text/xml'),
    /* Give the client the XML */
    print($result[0]);
} catch (SoapFault $ex) {
    /* Something went wrong, show the exception */
    print($ex);
}
?>

It’s that easy to add news to an application.

When Flickr went live, it became an instant success and attracted millions of people who began to share their photos with the rest of the world. Since that time, other sites have been created with the same basic functionality, but with slightly different services. More important, communities exist within each of these sites, and they create many levels of communication and sharing between people all over the globe.

To increase their popularity and appeal to the development community, these photo services began to release APIs for their software so that outside web applications could reproduce the functionality offered on each site. These APIs help developers relatively easily do some pretty cool things in their web applications using web services like Flickr.

The following are some of the more popular photo APIs available:

Flickr is one of the more popular services, so I’ll use it as an example. Flickr allows developers to request information from its web service in the REST, XML-RPC, and SOAP formats. An example REST request would look like this:

http://api.flickr.com/services/rest/?method=flickr.test.echo&name=value

Generally, the response format will be the same as that of the request, so a REST request would get a REST response. You can change the default response type using the format parameter in the request:

<?php
/* Set up the parameters for the request */
$params = array(
    'api_key'    => '[API key]',
    'method'    => 'flickr.blogs.getList',
    'format'      => 'json'
);

$encoded_params = array( );
/* Loop through the parameters and make them safe */
foreach ($paramas as $param => $value)
    $encoded_params[] = urlencode($param).'='.urlencode($value);
?>

There will be some debate as to which of Flickr’s response formats is the easiest to use. The choices are formatted XML with REST, XML-RPC, and SOAP; JavaScript Object Notation (JSON); and serialized PHP. The REST response is an easy response format to use, as it is a simple XML block. JSON, however, also has its advantages in size and structure. A successful JSON response is in this format:

jsonFlickrApi({
    "stat": "ok",
    "blogs": {
        "blog": [
            {
                "id"                 : "23",
                "name"               : "Test Blog One",
                "needspassword"      : "0",
                "url"                : "http://blogs.testblogone.com/"
            },
            {
                "id"                 : "76",
                "name"               : "Second Test",
                "needspassword"      : "1",
                "url"                : "http://flickr.secondtest.com/"
            }
        ]
    }
});

Meanwhile, if an error occurs, the JSON returned looks like this:

jsonFlickrApi({
    "stat"      : "fail",
    "code"      : "97",
    "message"   : "Missing signature"
});

Many methods are available with the Flickr API, as shown in Table 18-5. These methods can be separated by functionality, which you can see by breaking down the Flickr method names. All Flickr methods begin with the flickr namespace, followed by the function category the method is in—activity, auth, favorites, and so on.

You can see from the length of Table 18-5 that the Flickr API covers just about anything a developer would want to do programmatically. Example 18-7 demonstrates how to make a REST request to the Flickr web service and get a JSON response that is sent to the client. The example gets the title of a specific photo on Flickr’s site that can be returned to the client.

<?php
/**
 * Example 18-7. Making a REST call to the Flickr web service and getting a
 * PHP response.
 *
 * This file demonstrates how to send a request to Flickr's API methods and
 * send the response to the client using the REST architecture and JSON.
 */

/* Set up the parameters for the request */
$params = array(
    'api_key'   => '[API key]',
    'method'    => 'flickr.blogs.getList',
    'format'    => 'json'
);

$encoded_params = array( );
/* Loop through the parameters and make them safe */
foreach ($paramas as $param => $value)
    $encoded_params[] = urlencode($param).'='.urlencode($value);

/* Make the API request */
$url = "http://api.flickr.com/services/rest/?".implode('&', $encoded_params);
$response = file_get_contents($url);
/* Send the response to the client to parse */
print($response);
?>

Example 18-8 demonstrates how easy it is to make the JSON response usable on the web page. It is also easy to modify this function to do something different from what it is doing.

/*
 * Example 18-8. Demonstrating how to handle a JSON response from Flickr.
 */

/**
 * This function, jsonFlickrResponse, takes the JSON response from the server
 * and parses the results by creating <div> elements to place the blog name in.
 * It sends the error code and message should an error occur in the request.
 *
 * @param {Object} p_xhrResponse The XMLHttpRequest response from the server.
 */
function jsonFlickrResponse(p_xhrResponse){
    var rsp = p_xhrResponse.responseText;

    /* Did we get a valid response? */
    if (rsp.stat == 'ok') {
        /* Loop through the log records */
        for (var i = 0, il = rsp.blogs.blog.length; i < il; i++) {
            var blog = rsp.blogs.blog[i];
            var div = document.createElement('div'),
            var txt = document.createTextNode(blog.name);

            div.appendChild(txt);
            document.body.appendChild(div);
        }
    /* Did we get a fail message? */
    } else if (rsp.stat == 'fail') {
        var div = document.createElement('div'),
        var txt = document.createTextNode(rsp.code + ': ' + rsp.message);

        div.appendChild(txt);
        document.body.appendChild(div);
    }
}

The Web is one great library, used to look up everything from antidisestablishmentarians to zooarchaeologists. OK, maybe not everything, but a great deal of content on the Web can be used as reference or for lookup. When sites such as Wikipedia arrived on the scene, the volume of information that could be referenced in one place skyrocketed.

Reference content is more than just articles on Wikipedia, however, a site which closely resembles encyclopedias of the past. The amount of information that can be gathered, from demographics to genealogical data, is really the reference information that I mean. Unfortunately, some of this information is still difficult to get in a single, usable form. From this chapter’s point of view, many reference sites still lack access as web services—even sites such as Wikipedia (at least as of the time of this writing, though a web service is in the works).

The following is a sample of some of the services available:

Something that is beginning to change, in small steps anyway, is the online availability of public information from local, state, and federal government agencies. However, a great deal of information still is not available on the Internet, or if it is, fees are associated with it. Only time will tell how much information will actually become available on the Internet, and what it will cost to access it.

Then there is the problem of sites that have good reference information available, whether or not a fee is involved. However, these sites have not created web services to access their information from outside their site frameworks. A major area where this is lacking is genealogical information. Again, in time, accessing reference information through web services will improve. We’ll just have to wait to see how long this will take.

I think it is pretty safe to say that if you have been on the Web, you have conducted a search of some kind. Let’s face it, it can be pretty hard to find the content you are looking for, especially as the Web gets older and more mature. There is so much information on the Web, even within a single site, that you would be hard-pressed to find what you were looking for without performing at least one search.

This was not always the case. In the late 1990s, it was much easier to find specific content simply because the Web did not have the volume of information it has today (this assumes that the content you were looking for even existed!). The reverse is true today; the content is out there, somewhere, but it is much harder to find. I admit that I usually start to browse the Web from a Google search page unless I already know the place I need to start from (we all have favorites and bookmarks, after all).

The Web relies on searching, whether it’s from a site such as Google or Yahoo! or from within a site; blogs are an example of sites that need internal searching. Having APIs to some of the better search engines available can greatly enhance a web application; developers can add the searching directly into the application, saving trips to other places.

The following is a sample of some of the search services available:

I touched on search service APIs in Chapter 16 where I explored some of the capabilities of Google’s AJAX Search API. The better APIs available are just as easy to use as Google’s is, and should not cause much trouble for developers to integrate them into an application.

Most business owners have recognized by now that if you have something to sell, you better have a way to sell it online. This is, in no small part, thanks to sites such as Amazon and eBay, which have made shopping on the Web simple, quick, and painless.

Instead of investing money into their own sites and shopping technology, many small to medium-size businesses have turned to larger commercial sites for hosting and the technology to drive their business. One disadvantage to this is a slight loss of brand recognition, as consumers will see what is driving shopping carts with less emphasis on the business that brought them there. The ability to use these sites from a separate application or web site through APIs has changed all that.

Web services that enable developers to access the functionality of these larger e-commerce sites allow for better site integration and smoother, more seamless business applications. The following is a list of some of the shopping applications available:

As a quick example of using a shopping service, let’s look at eBay. eBay has done an awesome job of documenting its API and providing examples on how to use it properly. The API can be called using REST or SOAP, and eBay provides examples on how to use the API with Java, PHP, C#, and ASP, among others.

The following is an example of a REST request to eBay:

http://rest.api.ebay.com/restapi?CallName=GetSearchResults&
RequestToken=[UserToken]&RequestUserId=[UserName]&Query=[Query Words]&
Version=491&UnifiedInput=1

This example calls the method GetSearchResults, and expects a maximum of five results. An eBay UserName and UserToken are required to use this service. Table 18-6 shows the methods available in eBay using the REST API.

Every eBay REST API method requires the same basic parameters when a client makes a request. Table 18-7 describes the required input parameters.

The best way to understand how eBay’s web service works is to see how the server side would make a request to the server when a variable is passed to it. Example 18-9 shows how to handle this in PHP.

<?php
/**
 * Example 18-9. Requesting search results from the eBay REST API.
 *
 * This file is an example of searching eBay using its REST API, utilizing the
 * CURL package to make the request and return the results.
 */

/* Was a search request received? */
if (isset($_REQUEST['search_text'])) {
    $request_token =    '[UserToken]';
    $request_user_id =  '[UserName]';
    $query = $_REQUEST['search_text'];

    /* Create the REST string */
    $rest_request = 'http://rest.api.ebay.com/restapi?'
        .'RequestToken='.$request_token
        .'&RequestUserId='.$request_user_id
        .'&CallName=GetSearchResults'
        .'&Schema=1'
        .'&Query=''.urlencode($query).'''
        .'&MaxResults=10'
        .'&SearchInDescription=1'
    ;

    try {
        $curl_request = curl_init( );
        /* Set the URL to post the request to */
        curl_setopt($curl_request, CURLOPT_URL, $rest_request);
        /* This allows for errors to be handled */
        curl_setopt($curl_request, CURLOPT_FAILONERROR, 1);
        /* This allows for redirection */
        curl_setopt($curl_request, CURLOPT_FOLLOWLOCATION, 1);
        /* This sets the response to be set into a variable */
        curl_setopt($curl_request, CURLOPT_RETURNTRANSFER, 1);
        /* This sets a timeout for 30 seconds */
        curl_setopt($curl_request, CURLOPT_TIMEOUT, 30);
        /* This sets the post option */
        curl_setopt($curl_request, CURLOPT_POST, 0);
        /* Execute the CURL process, and set the results to a variable */
        $result = curl_exec($curl_request);
        /* Close the connection */
        curl_close($curl_request);
    } catch (Exception $ex) {
        $result = $ex.message;
    }
} else
    $result = "A search request was not sent.";
print ($result);
?>

Example 18-9 uses the CURL package, which must be installed on the web server on which the code will be executed. You will notice that I set some additional parameters as part of the GetSearchResults request. Here is a list of the parameters available to set with this method: Query, Category, ItemTypeFilter, PayPal, SearchInDescription, LowestPrice, HighestPrice, PostalCode, MaxDistance, Order, MaxResults, and Skip. Any of these could be sent as part of the request from the client; the server-side script would simply need to be modified to handle those $_REQUEST parameters as well.

Of course, other services are available, but they do not fit well into a broad category. Furthermore, they range in functionality and complexity. If a developer needs a service, more than likely she will be able to find it on the Web somewhere with a bit of investigating. If a service has not been created yet, a few posts to forums might reveal someone else with the same needs. Collaborative efforts often produce great results.

The following is a sample of some of the other services available:

True Ajax functionality is such because the call to the web service is controlled by a server script, and the client will use the XMLHttpRequest object to tell it what to do. The client must have knowledge of the service that will be used so that it can pass any necessary parameters to the server making the call. Like all Ajax calls, it must also know what will be coming back in the response.

Based on the client’s needs, a well-formed XHTML response could be sent that “plugs” right in to a part of the client. Services that update frequently can save time working this way for ease of use and functionality. Good examples of these are weather services, stock services, and any other small stat-based service. The other nice thing about Ajax approaches of this nature is that the client couldn’t care less about the protocol that will be used to call the web service. REST will be used for all communication with the server, and it is the developer’s decision whether to use GET or POST as the method of sending requests to the server. This helps to keep the client component of the web service call very simple. The other simple component in the model is the web service component itself, and it is simple only because the developer usually has no control over it.

The intermediary between the client and the web service, our server script, is where all of the real functionality lies. I intentionally did not say complexity or difficulty in that last sentence, as it does not have to be either in a lot of cases, and it would be misleading to say that it is. Figure 18-2 shows what the different parts of a web service model look like.

Figure 18-2. A simple model showing the use of the XMLHttpRequest object to facilitate calling web services from the server

As you can see from Figure 18-2, the use of the XMLHttpRequest object allows a single page to make multiple requests for web services on the server. Without Ajax, the page would have to do the calling itself, which would then require a refresh of the entire page.