Pre-requisites

The following libraries are required to be downloaded:

java 6
apache httpclient 4.2.3
apache httpcore 4.2.2
apache httpmimi 4.2.3
java-json.jar

Version

1.0

Description

zuora-rest-java facilitates developers to build Java based
Zuora applications without being burdened by the underlying HTTP mechanics,
multi-threading, proxy, SSL security, error handling, and logging support 
required for debugging and troubleshooting. Complex JSON responses and call
arguments can also be manipulated using simple Java setter and getter methods.

The sample code demonstrates how all Zuora REST resources can be modeled
as "resource manager". There are 8 resource manager classes: Connection,
Catalog, Payment_Method, Account, Subscription, Transaction, Operation
and Usage. Three sample usage files are also provided.

Features

. Environment neutral. Support JSE or JEE

. Support configuration for local installation needs

. Provide full API pre-call and post-call trace for easy debugging

. Provide log files as support documentation

. Support multi-threading environment with http connection pooling

. Navigate call arguments and JSON response string using setter and getter

. Support VERIFY NONE and VERIFY PEER for SSL invocations

. Support proxy, including basic authentication

Configuration

Support global configuration via a configuration properties file in the
"resource" subdirectory. This can be customized and built into the target
jar file and used by the developers as the default configuration and
further simply code.

Different applications can also use different configuration. This is
achieved by including a local copy of a ZConfig.properties in the working
directory (i.e. pwd) where the application runs.

Change Installation specific properties as needed. Most default settings
work in most installations, but some are installation specific properties:

. Setting default tenant's credentials enables a connect call to be made
  without arguments - remove security sensitive information from developers.

. if using forwarding proxy server set proxy.used to true

. If the proxy uses basic authentication set proxy.auth to true, and its
  credentials in proxy.user and proxy.password.

. When developing switch on api trace for debugging. Set api.trace to true.

. If you are worried about the authenticity of the api end point
  set ssl.verify to true. This may slightly degrade performance on CONNECT
  calls.

Logging

SDK puts all log files in the subdirectory "sdk_logs" under the current
working directory where the application runs.

sdk.log is for the sdk itself.

api_trace.log is for API debugging.

When reporting an incident report to Zuora, both logs should be sent as
documentation.

Each log files has a 4M size limit and up to 3 generations before it is
wrapped around.

Examples

Refer to the samples for the following discussion. You
can write your own resource managers or any other abstraction; they are only
there to illustrate one way of designing application objects around the
APIs.

1. import the necessary jars

2. All calls must be routed through ZClient. To create a ZClient:

        ZClient zClient = new ZClient();

   Use the get, put, post, and delete methods to send a REST API.

3. Pass the zClient object to the resource manager object.

4. Prepare arguments

   All arguments are ultimately put inside a JSON structure. Some arguments,
   mandatory or optional, are required to be created in some nested structure.

   Use the ZAPIArgs class which allows argument object to be manipulated via
   its setter and getter methods. Whenever there is a need for a nested
   argument structure, use new ZAPIArgs. Refer to sample code and the
   corresponding published call arguments in the API documentation
   for more sample usage.

   There are 4 key attributes in ZAPIArgs that are needed to make a REST
   API call:

   uri
    Refers to the resource uri (excluding the API endpoint). For instance
        ZAPIArgs args =  new ZAPIArgs();
        args.set("uri", "/catalog/products");

    Predefined resource endpoints are provided as samples and can be found
    in ResourceEndpoints.java

   headers
    Used as fields in request header. Only relevant to the CONNECT API
        ZAPIArgs args =  new ZAPIArgs();
        args.set("headers", new ZAPIArgs());
        args.getArg("headers").set("apiAccessKeyId", "your_username");
        args.getArg("headers").set("apiSecretAccessKey", "password");

    If indded th ZConfig.properties file has the default tenant's credentials
    configured, these headers will not be needed when connecting to
    the default tenant.

   queryString
    Also known as HTTP parameters. For instance:

        ZAPIArgs args =  new ZAPIArgs();
        args.set("query_string", new ZAPIArgs());
        args.getArg("query_string").set("pageSize", 20);

   reqBody
    Most POST and PUT APIs require substantial amount of arguments to be set
    up in the request body of the HTTP request. This needs to be set up
    before the request can be sent to the service provider.

        ZAPIArgs args =  new ZAPIArgs();
        args.set("req_body", new ZAPIArgs());
        args.getArg("req_body").set("name", "api_tester");
        args.getArg("req_body").set("billToContact", new ZAPIArgs());
        args.getArg("req_body").getArg("billToContact").set("firstName", "api");
        args.getArg("req_body").getArg("billToContact").set("lastName", "Tester");

   Consult Zuora REST API documentation for details of the call arguments.

5. Authenticate to the endpoint using tenant's user id and password:

    connect()           # connect with pre-configured tenant's credentials
    
   To provide tenant's credentials on the fly:

    connect("box.net", "secretPassword")

6. Check response

   Both the HTTP Status Code and Response Phrase are always included
   in the response object ZAPIResp. If the invocation had been successful,
   ZAPIResp also contains the body of the HTTP response.

   The response attributes can be parsed using getter method. For
   instance:

        response.get("nextPage")

   To reach the response in a nested structure, use the getResp method.

   Refer to Zuora REST API documentation for details of the call arguments
   and the sample resource managers for more examples.

7. Catch exceptions

   If the syntax of the arguments are wrong, for example, missing body or
   presence of extraneous arguments, the SDK will raise an
   IllegalArgumentException with the corresponding diagnostic message.

   If there is an exception while the call is in progress, a RuntimeException
   will be raised, and the corresponding stack trace will also be
   logged in both the sdk and api_trace log files.

8. Follow the "nextPage"
   When issuing a GET call, sometimes there are multiple pages of response
   returned.

   This is indicated by the presence of the "nextPage" key in the response
   body.

   For example, in the get_all method of the PaymentMethod resource
   manager, if the nextPage key is present in the response, pass nextPage
   as the url and make a recursive call.

How To

1. To run the samples:
	
	mvn test
	
2. To import this maven project into Eclipse:
	
	mvn eclipse:eclipse

Author

Zuora Inc.

Copyright

Copyright (c) 2013 Zuora Inc. (http://www.zuora.com).
See License for details