Pre-requisites
The following gems are required:
httpclient, >= 2.3.1
json_pure, >= 1.7.6
hashie, >= 1.2.0
awesome_print >= 1.1.0
Installation
From github after download
gem install --local z_ruby_sdk-1.0.gem
Version 1.0
Description
zuora-rest-ruby facilitates developers to build Ruby 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 ruby 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
. Support MRI Ruby 1.8.7 or above
. Support JRuby (no native code in the gem)
. Environment agnostic. Support pure ruby script and Rails
. 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 z_config.yml located in the config
subdirectory. This can be customized 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 z_config.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 filing 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. require 'rubygems'
require 'z_ruby_sdk'
2. All calls must be routed through Z_Client. To create a Z_Client:
z_client = Z_Client.new
Use the get, put, post, and delete methods to send a REST API.
3. Pass the client 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
simply like attributes. 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
The resource uri (excluding the API endpoint). For instance
args = ZAPIArgs.new
args.uri = "/catalog/products"
Predefined resource endpoints are provided as samples and can be found
in resource_endpoints.rb
headers
Used as fields in request header. Only relevant to CONNECT API
args = ZAPIArgs.new
args.headers = ZAPIArgs.new
args.headers.apiAccessKeyID = "api_tester"
args.headers.apiSecretAccessKey = "password"
If a ZConfig.properties file has the default tenant's credentials
configured, these headers will not be needed when connecting to
the default tenant.
query_string
Also known as HTTP parameters. For instance
args = ZAPIArgs.new
args.query_string = ZAPIArgs.new
args.query_string.pageSize = 20
req_body
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.
args = ZAPIArgs.new
args.req_body = ZAPIArgs.new
args.req_body.name = "api_tester"
args.req_body.billToContact = ZAPIArgs.new
args.req_body.billToContact.firstName = "api"
args.req_body.billToContact.lastName = "Tester"
Consult the 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("tenant_chief", "secretPassword")
6. Check response
When the call is passing a block in one of the Z_Client methods (get,
put, post, or delete), the http response body is passed back to
the block.
If no block is passed, the response body is returned directly.
Both the HTTP Status Code and Response Phrase area 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 addressed like attributes. For
instance:
response.nextPage
response.subscription[0].subscriptionNumber
7. Catch exceptions
If the syntax of the arguments are wrong, the SDK will raise an
ArgumentError with the corresponding diagnostic message.
If there is an exception while the call is in progress via the httpclient
library a RuntimeError will be raised, and stack trace will also be
logged in both the sdk and api 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 payment_method manager,
if the nextPage key is present in the response, pass nextPage
as the url and make a recursive call.
9. Iterate ZAPIResponse programmatically
See sample class zapiresp_iterator.rb.
Author
Zuora Inc.
Copyright
Copyright (c) 2012-2013 Zuora Inc. (http://www.zuora.com).
See License for details