The SOAP::Lite modules can be installed by:

1. Using the system package manager install/update the appropriate package, for example libsoap-lite-perl for Debain based Linux systems (e.g. Ubuntu or Bio-Linux)
2. Using CPAN to install/update SOAP::Lite (CPAN).
3. Downloading the SOAP::Lite distribution and installing manually:
   • from CPAN
   • from http://www.soaplite.com/

For an overview of the how to install a module see Installing Perl Modules.

Note: check the version of SOAP::Lite before installing, there are known issues with some versions.

There are three ways to use SOAP::Lite to access a SOAP Web Service:

1. Generate a dynamic interface to the service (service proxy) from a WSDL at runtime
2. Generate a static interface to the service (service proxy) from a WSDL
3. Directly invoke SOAP calls against the service

The service proxy object, which is used to access the service operations, can be generated from a WSDL using the SOAP::Lite→service($WSDL) method. This works for most RPC/encoded services and for many document/literal services.

For example: fetching the WAP_RAT UniProtKB entry using WSDbfetch (examples/SOAP/SOAP-Lite/dbfetch_soaplite.pl)

# SOAP::Lite module
use SOAP::Lite;
 
# WSDbfetch WSDL URL
my $WSDL = 'http://www.ebi.ac.uk/ws/services/WSDbfetch?wsdl';
# Default option values
my ($query, $format, $style) = ('uniprot:wap_rat', 'fasta', 'raw');
 
# Create a service proxy from the WSDL. Specifying a SOAP fault handler which maps a fault to a die.
my $soap = SOAP::Lite
    ->service($WSDL)
    ->on_fault(sub { # SOAP fault handler
        my $soap = shift;
        my $res = shift;
        # Map faults to exceptions
        if(ref($res) eq '') {
            die($res);
        } else {
            die($res->faultstring);
        }
        return new SOAP::SOM;
	       }
    );
 
# Perform the query
my $result = $soap->fetchData($query, $format, $style);
# Output the result
print $result;

The WSDbfetch web service (http://www.ebi.ac.uk/Tools/webservices/services/dbfetch) provides the same basic functionality as dbfetch, but through a SOAP interface.

Using the example WSDbfetch client (examples/SOAP/SOAP-Lite/dbfetch_soaplite.pl) as a guide, use the service to fetch the UniProtKB entries with the accessions: P13569, P26361 and P35071, in fasta format.

Sample solution: solutions/SOAP/SOAP-Lite/q1_dbfetch_soaplite.pl

SOAP::Lite includes a utility (stubmaker or stubmaker.pl) to generate static code stubs from a WSDL document:

stubmaker.pl http://www.ebi.ac.uk/ws/services/WSDbfetch?wsdl

This generates a Perl module (.pm) named after the Web Service described in the WSDL (e.g. WSDBFetchServerService.pm) which implements a static version of the SOAP::Lite->service($WSDL) style service proxy.

The generated Perl module is used by loading the module and creating an instance of the class named for the service. For example for the WSDbfetch service (examples/SOAP/SOAP-Lite/dbfetch_soaplite_stubs.pl):

# Load generated stubs
use WSDBFetchServerService;
 
# Get service proxy
my $soap = new WSDBFetchServerService->new();
# Add a fault handler to map a fault to a die
$soap->on_fault(
	sub { # SOAP fault handler
    	my $soap = shift;
        my $res = shift;
        # Map faults to exceptions
        if(ref($res) eq '') {
            die($res);
        } else {
            die($res->faultstring);
        }
        return new SOAP::SOM;
	}
);
 
# Parameter values
my ($query, $format, $style) = ('uniprot:wap_rat', 'fasta', 'raw');
# Perform the query
my $result = $soap->fetchData($query, $format, $style);
# Output the result
print $result;

Generate static stubs for WSDbfetch using stubmaker. Check that the stubs have been generated successfully by running the stubs based client: examples/SOAP/SOAP-Lite/dbfetch_soaplite_stubs.pl.

The WSDbfetch service includes a number of meta-data methods which provide information about the service such as the names of the databases available, and the formats and styles which can be used with each database (see http://www.ebi.ac.uk/Tools/webservices/services/dbfetch).

Starting from the stubs based client (examples/SOAP/SOAP-Lite/dbfetch_soaplite_stubs.pl), use the getDbFormats() method of the WSDbfetch service to determine what the available data formats are for the UniProtKB database.

Sample solution: solutions/SOAP/SOAP-Lite/q3_dbfetch_soaplite_stubs.pl

If a WSDL is not available for the Web Service, then direct calls can be made to the service using the call method. For example using WSDbfetch by performing direct calls (examples/SOAP/SOAP-Lite/dbfetch_soaplite_call.pl):

# Load the SOAP library
use SOAP::Lite;
 
# Service details
my $NAMESPACE = 'http://www.ebi.ac.uk/ws/services/WSDbfetch';
my $ENDPOINT = 'http://www.ebi.ac.uk/ws/services/WSDbfetch';
 
# Create interface to the service
my $soap = new SOAP::Lite(uri   => $NAMESPACE,
                          proxy => $ENDPOINT);
# Add a fault handler to map a fault to a die
$soap->on_fault(
	sub {    # SOAP fault handler
		my $soap = shift;
		my $res  = shift;
 
		# Map faults to exceptions
		if ( ref($res) eq '' ) {
			die($res);
		}
		else {
			die( $res->faultstring );
		}
		return new SOAP::SOM;
	}
);
 
# Parameter values
my ($query, $format, $style) = ('uniprot:wap_rat', 'fasta', 'raw');
# Perform the query
my $result = $soap->call('fetchData' => $query, $format, $style);
# Output the result
print $result->result;

While SOAP::Lite→service() works for many SOAP services, in some cases it is necessary to use a lower level approach to ensure the messages are decoded correctly, while retaining WSDL support.

For example: the getResultsIds(domain, query, start, size) method of the EB-eye service always returns a single ID using the default behavior. By changing to using SOAP::Lite→uri()→proxy(), which provides direct access to the messages, the result can be extracted from the response document using XPath. Thus all the IDs matching the query can be obtained (examples/SOAP/SOAP-Lite/ebeye_soaplite.pl):

# Load modules
use SOAP::Lite;
 
# EB-eye namespace and endpoint (from WSDL)
my $NAMESPACE = 'http://webservice.ebinocle.ebi.ac.uk';
my $ENDPOINT  = 'http://www.ebi.ac.uk/ebisearch/service.ebi';
 
# Chunk size for getting results
my $chunkSize = 50;
# Query details
my ( $domain, $query ) = ( 'uniprot', 'azurin' );
 
# Create the service proxy and define a fault handler
my $soap = SOAP::Lite->uri($NAMESPACE)->proxy($ENDPOINT)->on_fault(
	sub {    # SOAP fault handler
		my $soap = shift;
		my $res  = shift;
 
		# Map faults to exceptions
		if ( ref($res) eq '' ) {
			die($res);
		}
		else {
			die( $res->faultstring );
		}
		return new SOAP::SOM;
	}
);
 
# Get identifiers matching the query
my ($response);
 
# First find out how many
$response = $soap->getNumberOfResults( $domain, $query );
my $numEntries = $response->valueof('//getNumberOfResultsResponse/numberOfResults');
 
print "$numEntries entries found for $query in $domain\n";
 
# Loop over results getting and printing each chunk.
for ( my $start = 0 ; $start < $numEntries ; $start += $chunkSize ) {
	# Get the chunk
	$response = $soap->getResultsIds( $domain, $query, $start, $chunkSize );
	my (@idList) = $response->valueof('//getResultsIdsResponse/arrayOfIds/string');
 
	# Print each ID
	foreach my $id (@idList) {
		print $id, "\n";
	}
}

The EB-eye web service (http://www.ebi.ac.uk/Tools/webservices/services/eb-eye) provides a method for searching a broad selection of the databases available at EMBL-EBI. As well a search functionality it also provides methods for exploring the data using links based on the cross-references present in the data.

Using the example EB-eye client (examples/SOAP/SOAP-Lite/ebeye_soaplite.pl) as a guide, use the EB-eye to find the number of entries in EMBL-Bank Coding Sequence (emblcds) which contain the term “CFTR”.

Sample solution: solutions/SOAP/SOAP-Lite/q4_ebeye_soaplite.pl

Like WSDbfetch the EB-eye web service provides methods to get details of the available search domains, the fields within the domains and details of cross-references.

Starting from the example EB-eye client (examples/SOAP/SOAP-Lite/ebeye_soaplite.pl) get the list of available domains (listDomains()) and the fields within these domains (listFields(domain)).

Sample solution: solutions/SOAP/SOAP-Lite/q5_ebeye_soaplite.pl

If the service call requires a complex input type this needs to be built. For example to submit a job to the FASTA (SOAP) service.

Create the SOAP::Data objects to be passed to the service (examples/SOAP/SOAP-Lite/fasta_soaplite.pl):

# Build parameters structure
my $params = SOAP::Data->name('parameters' =>
	\SOAP::Data->value(
		SOAP::Data->name('program'    => 'fasta'), # Program to perform search
		SOAP::Data->name('database'   => [ # Database(s) to search
			SOAP::Data->type('string' => 'pdb')->name('string')->attr({'xmlns' => ''})
		]), 
		SOAP::Data->name('scores'     => 10), # Number of hit summary scores
		SOAP::Data->name('alignments' => 10), # Number of hit alignments
		SOAP::Data->name('stype'    => 'protein'), # Sequence type
		SOAP::Data->name('sequence' => $query_sequence) # Query sequence
	)
);
 
# Submit the job
print STDERR 'Sumbit job...', "\n";
my $jobid = $soap->run(
	SOAP::Data->name('email' => $email)->attr({'xmlns' => ''}),
	SOAP::Data->name('title' => $title)->attr({'xmlns' => ''}),
	SOAP::Data->name('parameters' => $params)->attr({'xmlns' => ''})
)->result;
print STDERR 'Job ID: ', $jobid, "\n";

See Complex SOAP::Lite requests - my rules for SOAP::Sanity! for a guide to building the complex structures required by some services.

Analytical tools may take sometime to complete so these tools need to be run using an asynchronous method. Where the submission returns a job identifier which can be then used to check on the status of the job, and once it completes retrieve the results. The FASTA (SOAP) service (http://www.ebi.ac.uk/Tools/webservices/services/sss/fasta_soap), which uses the FASTA suite to perform a sequence similarity search is one service that requires this approach.

Examine the example client (examples/SOAP/SOAP-Lite/fasta_soaplite.pl) and note the “run”, “getStatus” and “getResult” work flow.

Using the example client as a guide, use FASTA (SOAP) to perform a FASTA search with UniProtKB CFTR_MOUSE against UniProtKB/SwissProt.

Sample solution: solutions/SOAP/SOAP-Lite/q6_fasta_soaplite.pl

The FASTA (SOAP) service can return the result in a number of formats, modify your client to use the getResultTypes() method to discover the other available result types.

Sample solution: solutions/SOAP/SOAP-Lite/q7_fasta_soaplite.pl

It is useful when debugging a client to be able to see the actual SOAP messages exchanged. SOAP::Lite provides a trace option which can be used to enable output of these messages:

SOAP::Lite->import(+trace => qw(debug));

If a SOAP fault handler (on_fault) is not defined then faults must be checked for explicitly:

# Check for fault and map into an exception.
if($soap->call->fault) {
  die $soap->call->faultstring;
}

Normally the SOAP fault handler (on_fault) is used to map a faults to a die so normal Perl exception handling can be used:

# Add a fault handler to map a fault to a die
$soap->on_fault(
	sub {    # SOAP fault handler
		my $soap = shift;
		my $res  = shift;
 
		# Map faults to exceptions
		if ( ref($res) eq '' ) {
			die($res);
		}
		else {
			die( $res->faultstring );
		}
		return new SOAP::SOM;
	}
);

In some environments it is necessary to configure an HTTP proxy before a client can connect to external services. SOAP::Lite supports two ways to set proxy information:

1. Additional options to the SOAP::Lite→proxy() call. For example:

   my $soap = SOAP::Lite->proxy(
   	$ENDPOINT,
   	timeout => 6000,    # HTTP connection timeout
   	proxy => ['http' => 'http://proxy.example.org/'] # HTTP proxy
     )->uri($NAMESPACE);

2. Setting information on the libwww-perl (LWP) object used for the HTTP transport. For example:

   $soap->transport->env_proxy(); # LWP to load proxy details from environment

See Proxies for more details regarding LWP support for HTTP proxies.

HTTP clients usually provide information about what they are, this allows services to handle specific clients differently if necessary, and gives service providers information about how their services are being used. By default SOAP::Lite sets the HTTP User-Agent header (see RFC2616 section 14.43) to something like SOAP::Lite/Perl/0.60, where the version number (0.60) is the version of SOAP::Lite. If additional identification of the client is required the a more specific product token (see RFC2616 section 3.8) should be added to the beginning of the User-Agent string:

# Modify the user-agent to add a more specific prefix (see RFC2616 section 14.43)
$soap->transport->agent("Example-Client/1.0 ($OSNAME) " . $soap->transport->agent());

Note: while the HTTP specification does not define a limit on the size of HTTP headers, web server implementations often do limit the maximum size of an HTTP header to 8KB or 16KB. If the server limit for an HTTP header is exceeded a “400 Bad Request” will be returned by the server.

SOAP::Lite provides support for on the fly compression of HTTP requests and decompression of HTTP responses (SOAP::Lite COMPRESSION), which can save bandwidth and improve the performance of data transfers between the client and the web service. To enable HTTP compression add the compress_threshold option, which sets the minimum size of a request to compress, when creating the service proxy. For example:

my $soap = SOAP::Lite->proxy(
	$ENDPOINT,
	timeout => 6000,    # HTTP connection timeout
	options => {
		# HTTP compression (requires Compress::Zlib)
		compress_threshold => 1024, # Prevent request compression.
	},
  )->uri($NAMESPACE);

Handling for compressed HTTP responses is enabled if the compress_threshold option is present, the value used does not matter. For HTTP request compression the request will only be compressed if it is larger than the specified compress_threshold, thus allowing request compression to be disabled through the use of large values.

If the web service does not support HTTP request compression and returns a HTTP status code of “415 Unsupported Media Type”, the request will be retried without compression. Note that not all web services return the required status for this case, and for those services it is necessary to disable HTTP request compression by using a large compress_threshold value to allow support for HTTP response compression.

Most SOAP Web Services at EMBL-EBI have sample clients which provide command-line access to the service and example code. For Perl most of the clients are based on SOAP::Lite.