112 lines
4.0 KiB
Markdown
112 lines
4.0 KiB
Markdown
# 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](http://developer.zappos.com/). 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 `SearchResult`s.
|
|
|
|
## 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.get().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](http://developer.zappos.com/) 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](http://maven.apache.org/).
|
|
|
|
## 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:
|
|
|
|
1. Copy the file `src/test/resources/apikey.properties.template` to `src/test/resources/apikey.properties`
|
|
2. 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.
|
|
|
|
# Copyright
|
|
|
|
All code herein is copyright 2012 Donald S. Black. Use and
|
|
redistribution are permitted under the terms of the
|
|
[GNU General Public License](http://www.gnu.org/licenses/gpl.html).
|