Zappy

This library provides limited interfaces to the Zappos REST API. Queries on the search, product, review, and image verbs are supported. Not all response fields are supported; a few are omitted because of limits on the number of fields that case classes can have in Scala.

The Zappos API has reasonably complete documentation at the Zappos API Web site. You will need an API key (available for free upon request from Zappos).

Using the library

There is a class in the dstu.zappy package for each of the supported API search predicates:

Search: search for products using a search term
Product: get detailed information for up to 10 products at once, addressing them by SKU, UPC, or stock ID
Review: get reviews for a product, addressing it by SKU
Image: get URLs of images of a product, addressing it by SKU

The constructors for each of these classes take parameters for your API key and any other information the API call needs (i.e., search terms or product IDs). Other parameters may be set using their respective withXXX or withoutXXX methods.

Most actions key off of a product ID. Product IDs are available in search results. Each API call has a unique response class. Some response classes contain a large set of results. For example, SearchResponse consists of the API call response code, search term, information about the number of search results, and list of a list of SearchResults.

Example: running a search

Using the API is much the same in Scala and Java. Scala can take advantage of the fact that most classes are case classes. Be sure to import scala.collection.JavaConversions._ to be able to treat the Java collections classes in the search result objects as Scala collections.

A simple search application that prints a three-column list of product ID, product name, and product URL to standard out is illustrated here:

:::java
import dstu.zappy.*;

public class SearchTest {
  public static void main(String[] args) {
    if (args.length != 3) {
	  System.err.println("Usage: SearchTest <API key> <search term> <maximum number of items to return>");
	  System.exit(-1);
    }
    String apiKey = args[0];
	String searchTerm = args[1];
	int itemLimit = Integer.parseInt(args[2]);
	Search s = new Search(apiKey, searchTerm).withLimit(itemLimit);
    for (SearchResult r : s.results()) {
	  System.out.println(r.productId() + "\t" + r.productName() + "\t" + r.productUrl());
	}
  }
}

If you wanted to, you could use the product ID for each search term to drill down and get review, image, or other specific product information for that product with the Review, Image, and Product classes. See the Zappos API documentation for definitions of the parameters that these API calls take and the fields of their response objects.

Building

Dependency resolution and the project build are managed with Maven.

Tests

Builds will automatically run tests that require a Zappos API key. If you would like to disable these tests, add the argument -DskipTests to all invocations of mvn.

If you wish to run these tests yourself:

Copy the file src/test/resources/apikey.properties.template to src/test/resources/apikey.properties
Fill in your API key on the appropriate line in apikey.properties

Installing in Maven locally

Run mvn install to install the library to your local Maven repository. Any other projects managed with Maven will be able to find it.

Building a standalone jar

If you don't manage your dependencies with Maven, you can still build a stand-alone jar to drop into your own project. Running mvn package will build jars in target/. You can add the -jar-with-dependencies.jar file that is built to your project's classpath, and you should be able to use Zappy from there.

4.0 KiB Raw Permalink Blame History