Working With SOAP

From API Documentation

Overview

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.

We recommend 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

This site has many code snippets based in SOAP, and maintains sample SOAP for a variety of calls and use cases in its Sample Code repository.

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.

Below, we outline common ways to capture SOAP in various programming environments.

Capturing SOAP/XML

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 three files: SENT.log, RECV.log, and TEST.log. These log files contain the messages sent, messages received, and trace information, respectively.

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:

1. Select the project by name, then right-click and point to Add
2. Select Add Existing Item.
3. In the Add Existing Item dialog, browse and select the SqlSoapTracer.cs file from the location you saved it to in step 1.
4. Select Show All Files and expand the Web References node. Select the Reference.cs file.
5. 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 lines of 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[0])); }

This registers a SOAP extension that invokes the SOAP tracing of these Web methods when they are executed.

Java

Save this file as client-config.wsdd in the working directory of your Axis client. Axis will load it automatically. The configuration here 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"/&gt; &lt;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

#!/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)