2.3. Displaying Photos from Flickr Using XML-RPC:

Flickr is primarily a photo-sharing service provided by Yahoo!, though it has recently branched out to offer other features. Basic accounts are free, and Flickr has a web service API that provides access via REST, SOAP, and XML-RPC. Because we've already covered SOAP and REST, we'll build our client using the XML-RPC architecture.

As you probably expected, you need a Flickr key before you can access their API. Since Flickr is a part of Yahoo!, you must set up a Yahoo! account first, then associate that account with the Flickr service. Start at www.flickr.com/signup, which walks you through the sign-up process. Once you've got your Flickr key, you're ready to start building your XML-RPC client.

To make an XML-RPC client for your Rails application you need to:

We'll demonstrate by getting the latest three images from Flickr using their interestingness.getList method. Update the code_controller.rb file from the previous examples to contain this new flickrtest method. Here is the code for our controller:

class CodeController < ApplicationController
  def flickrtest
     flickruri = flickr.com/services/xmlrpc/"
     server = XMLRPC::Client.new2(flickruri)
     flickrkey = "YOUR FLICKR KEY"
     details = {:api_key => flickrkey, :per_page => "3"}
     result = server.call("flickr.interestingness.getList", details)
     @doc = REXML::Document.new result
   end
end

And here's the view that displays the images and their titles. Save the following code as flickrtest.rhtml in the app/views/code/ directory):

<%
@doc.root.each_element do |res|
  image_url = "http://static.flickr.com/" \
   "#{res.attributes["server"]}/" \
   "#{res.attributes["id"]}_#{res.attributes["secret"]}.jpg"
%>
   <%= image_tag(image_url, :border => "0", :height => "100") %><br>
   <%= res.attributes["title"] %>
   <br><br>
<% end %>

Once more, that's all there is to it! You should now be able to test your application at http://localhost:3000/code/flickrtest.

Flickr results from our XML-RPC web service client

flickertest uses one extra Ruby library: the XMLRPC library. XMLRPC is a pure Ruby implementation of the XML-RPC specification. It comes standard with the Ruby 1.8.4 distribution. XMLRPC is also automatically loaded and ready for use by your Rails application. For full documentation and more information, to report bugs, or to obtain the latest version of XMLRPC,www.ntecs.de/projects/xmlrpc4r/.

Making XML-RPC calls is simple and straightforward. We start by creating an instance of our driver:

    flickruri = flickr.com/services/xmlrpc/"
server = XMLRPC::Client.new2(flickruri)

Then we make our actual method calls:

details = {:api_key => flickrkey, :per_page => "3"}
result = server.call("flickr.interestingness.getList", details)

We set up a Hash to pass the Flickr key and to limit results to the top three items, because the Flickr documentation states the service expects a structure data type. The XMLRPC library, like the SOAP4R library, automatically maps a Ruby Hash to a web service struct data type (also known as a complex data type) when it creates our outgoing request. We don't have to do any additional mapping between the service and native Ruby types on either outgoing or incoming requests.

Finally, as in the REST example, we convert our results into a REXML document that we can then parse:

@doc = REXML::Document.new result

We need to convert the results into a REXML document because the Flickr interestingness.getList method returns results as a simple string containing the representation of an XML document. In general, though, complex XML-RPC results are accessed just like the SOAP results in the previous example were: either as methods or as a hash.

Once we have molded our results into a REXML document, we can then parse the document. Flickr's online documentation tells us how to build the URL to display images from our results and how to display the title for each image:

<%
@doc.root.each_element do |res|
  image_url = "http://static.flickr.com/" \
   "#{res.attributes["server"]}/" \
   "#{res.attributes["id"]}_#{res.attributes["secret"]}.jpg"
%>
   <%= image_tag(image_url, :border => "0", :height => "100") %><br>
   <%= res.attributes["title"] %>
   <br><br>
<% end %>

In just a few short pages and with very little code, we've built working REST, SOAP, and XML-RPC clients for three of the most popular public web services available today! But we're just getting started. The next section shifts the focus from clients to servers. This is where Rails kicks it up yet another notch, making things even easierand in my opinion more funfor developers.