Yahoo Search Restful Client using Jersey

Yahoo Search provides a RESTful interface for web search. Of course this service is been there for a while. I was just curious to use Jersey Client to play around with the Yahoo REST service. It opens up a world of possibilities for building applications around these services in Java.

Let us invoke the web search API using GET and context search API using POST as described in the following URLs.

http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=finances&format=pdf (GET)

http://search.yahooapis.com/WebSearchService/V1/contextSearch (POST)
appid=YahooDemo&query=madonna&context=Italian+sculptors+and+painters+of+the+renaissance+favored+the+Virgin+Mary+for+inspiration

The URL is constructed using the actual query parameters for accessing web resources which takes the URL encoded “argument=value” form.

The below code shows how we can quickly write a Jersey based REST client for invoking these RESTful web services. The APIs are fairly self-explanatory.

import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.representation.Form;
import restful.search.jaxb.ResultSet;
import restful.search.jaxb.ResultType;

import javax.ws.rs.core.MediaType;

public class YahooRestfulSearchClient {
    public static void main(String args[]) {
        Client client = Client.create();
        WebResource r = client.resource("http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=finances&format=pdf");
        ResultSet searchResults = r.accept(MediaType.APPLICATION_XML).get(ResultSet.class);
        for (ResultType result : searchResults.getResult()) {
            System.out.println("Title : " + result.getTitle());
            System.out.println("Summary : " + result.getSummary());
            System.out.println("Url : " + result.getUrl());
        }

        Form form = new Form();
        form.add("appid", "YahooDemo");
        form.add("query", "madonna");
        form.add("context", "Italian sculptors and painters of the renaissance favored the Virgin Mary for inspiration");

        r = client.resource("http://search.yahooapis.com/WebSearchService/V1/contextSearch");
        searchResults = r.accept(MediaType.APPLICATION_XML).post(ResultSet.class, form);        
        for (ResultType result : searchResults.getResult()) {
            System.out.println("Title : " + result.getTitle());
            System.out.println("Summary : " + result.getSummary());
            System.out.println("Url : " + result.getUrl());
        }        
    }
}

I updated my original approach for invoking the Context search based on the suggestions from Jersey developers to use Jersey form parameters encoded in the body of the request instead of directly constructing the URI as a request entity in the post call. Typically, POST is used to create web resources. But, Yahoo documentation suggests that POST be used for context searches just because the query params can sometimes be potentially lengthy, and hence the recommendation to send query parameters in the POST data block. The other option in Jersey is to use the UriBuilder to construct the URI and add query parameters to the URI. The code snip below shows this latter approach. Using form parameters is more elegant than constructing lengthy URIs 🙂

        URI uri = UriBuilder.fromPath("http://search.yahooapis.com/WebSearchService/V1/contextSearch").queryParam("appid", "YahooDemo").queryParam("query", "madonna").queryParam("context", "Italian sculptors and painters of the renaissance favored the Virgin Mary for inspiration").build();
        r = client.resource(uri);
        searchResults = r.accept(MediaType.APPLICATION_XML).post(ResultSet.class);

In both these approaches, the crux lies in the response type ‘ResultSet’ which is described in the below schema for the responses returned from the Yahoo REST service. You can access the schema here. Here is a quick look at the schema.

Use this schema to generate your JAXB types (ResultSet, ResultType, CacheType) and you are ready to consume the response within your REST client. The best part of this exercise was using IntelliJ IDEA 8.0M1. This latest release has support for REST client plugin where you can test your restful resources and it supports RESTful development using Jersey. More to explore on this front. Here is a screen shot of IDEA8 Rest Client in action.