Working With SOAP
The Z-Commerce API is built using the Simple Object Access Protocol, or "SOAP." The advantage of using SOAP is that it is an industry standard, works with XML which is easily read by both humans and computer, and almost all programming frameworks have built-in libraries that make using SOAP simple.
Using the SOAP XML
Zuora recommends that when you are working and debugging your applications using the Z-Commerce API, inspect and use the SOAP (XML) to identify what is happening in your code. Inconsistencies or subtleties can be overlooked when programming, but working with XML allows for more precise error checking.
Sample SOAP: Capturing SOAP/XML
The Zuora API documentation includes many code samples based in SOAP. Many developers new to SOAP often do not realize that their programming is only generating and receiving XML from a webservice. Even if they do, they are often unsure how to view the XML, even when debugging their code.
The following sections provide examples of common ways to capture SOAP in various programming environments.
Perl
#!/usr/bin/perl use strict; use warnings; use SOAP::Lite +trace => 'all'; my ($SOAP_BASE, $USERNAME, $PASSWORD) = @ARGV; my $contact_client = SOAP::Lite->new ( proxy => $SOAP_BASE . 'contact.php', ns => 'urn:ContactService', ); my $token = $contact_client->login($USERNAME, $PASSWORD)->result;
PHP5
list(, $SOAP_BASE, $USERNAME, $PASSWORD) = $argv; $contact_client = new SoapClient($SOAP_BASE . 'contact.php?wsdl', array('trace' => true)); $token = $contact_client->login($USERNAME, $PASSWORD); $soap_request = $contact_client->__getLastRequest(); $soap_response = $contact_client->__getLastResponse(); echo "SOAP request:\n$soap_request\n"; echo "SOAP response:\n$soap_response\n";
PHP4
require_once('lib_soap/nusoap.php'); list(, $SOAP_BASE, $ADV_USERNAME, $ADV_PASSWORD) = $_SERVER['argv']; $contact_client = new SoapClient($SOAP_BASE . 'contact.php?wsdl', true); $token = $contact_client->call('login', array('user' => $ADV_USERNAME, 'pass' => $ADV_PASSWORD)); echo "SOAP request:\n" . $contact_client->request . "\n"; echo "SOAP response:\n" . $contact_client->response . "\n";
C++
Compile the stdsoap2.cpp source code with C/C++ compiler option '-DDEBUG' ('/DDEBUG' in MSVC++). Executing your service or client application logs the activities in the following files:
- SENT.log: This file contains the messages sent.
- RECV.log: This file contains the messages received.
- TEST.log: This file contains the trace information.
C#
Save the following code with the name SqlSoapTracer.cs in the same folder that contains the SOAP client project files.
Perform the following steps in the Solution Explorer window:
- Select the project by name, then right-click and point to Add.
- Select Add Existing Item.
- In the Add Existing Item dialog, browse and select the SqlSoapTracer.cs file from the location you saved it to in step 1.
- Select Show All Files and expand the Web References node. Select the Reference.cs file.
- In the Code Editor window, update the Reference.cs file by locating the entry points for your Web methods. To add SOAP trace support when the Web methods execute in client code, add the following snoopattribute() call in the Reference.cs code directly before the entry point for each Web method you want to trace, as shown in the following sample code.
[System.Web.Services.Protocols.SoapRpcMethodAttribute("urn:ContactService#login", RequestNamespace="urn:ContactService", ResponseNamespace="urn:ContactService")] [return: System.Xml.Serialization.SoapElementAttribute("token")] [snoopattribute()] public string login(string user, string pass, login_options login_options) { object[] results = this.Invoke("login", new object[] { user, pass, login_options}); return ((string)(results[
Java
Save this file as client-config.wsdd in the working directory of your Axis client. Axis will load it automatically. This configuration tells Axis to save all incoming and outgoing XML into a file named axis.log.
<deployment xmlns="http://xml.apache.org/axis/wsdd/" xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"> <handler name="log" type="java:org.apache.axis.handlers.LogHandler"/> <globalConfiguration> <requestFlow> <handler type="log"/> <requestFlow> <responseFlow> <handler type="log"/> <responseFlow> <globalConfiguration> <transport name="http" pivot="java:org.apache.axis.transport.http.HTTPSender"/> </deployment>
Ruby
#!/usr/bin/ruby require "soap/wsdlDriver" (soap_base, username, password) = ARGV contact_client = SOAP::WSDLDriverFactory.new(soap_base + 'contact.php?wsdl').create_rpc_driver contact_client.wiredump_dev = STDOUT; token = contact_client.login(username, password, nil)
Python
When using SOAPpy, make sure to add the import tag below for the object.api.zuora.com schema:
<import namespace=”http://api.zuora.<wbr/>com/” />
And also the import tag below for the api.zuora.com schema:
<import namespace=”http://object.api.<wbr/>zuora.com/” />
#!/usr/bin/python import sys import SOAPpy SOAPpy.Config.debug = 1 (SOAP_BASE, USERNAME, PASSWORD) = sys.argv[1:4] contact_client = SOAPpy.SOAPProxy(SOAP_BASE + 'contact.php') token = contact_client.login(USERNAME, PASSWORD)
Tips
If you are using the GlassFish application server, add the following configuration information to the domain.xml
file:
<jvm-options>-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog</jvm-options> <jvm-options>-Dorg.apache.commons.logging.simplelog.showdatetime=true</jvm-options> <jvm-options>-Dorg.apache.commons.logging.simplelog.log.httpclient.wire=debug</jvm-options> <jvm-options>-Dorg.apache.commons.logging.simplelog.log.org.apache.commons.httpclient=debug</jvm-options>