SOAP::Lite

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

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

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 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";
	}
}

SOAP::Lite includes a utility 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 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;

If the service call requires a complex input type this needs to be built. For example to submit a job to the WSFasta 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('params' =>
	\SOAP::Data->value(
		SOAP::Data->name('email'      => 'email@example.com'), # User e-mail address
		SOAP::Data->name('program'    => 'fasta3'), # Program to perform search
		SOAP::Data->name('database'   => 'pdb'), # Database to search
		SOAP::Data->name('scores'     => 10), # Number of hit summary scores
		SOAP::Data->name('alignments' => 10), # Number of hit alignments
		SOAP::Data->name('async' => 1)->type('xsd:boolean') # Asynchronous submission
	)
);
 
# Build input data structure
my $inSeq = <<EOF
>TestSeq
MRFIHALLLAGIAHSAYASEKLTFKTDLEKLEREKAAQIGVAIVDPQGEIVAGHRMAQRF
AMCSTFKFPLAALVFERIDSGTERGDRKLSYGPDMIVEWSPATERFLASGHMTVLEAAQA
AVQLSDNGATNLLLREIGGPAAMTQYFRKIG
EOF
  ;
my $data = SOAP::Data->name('content')->value(
	[\SOAP::Data->value(
		SOAP::Data->name('type' => 'sequence'),
		SOAP::Data->name('content' => $inSeq)
	)]
);
 
# Submit the job
print STDERR 'Sumbit job...', "\n";
my $jobid = $soap->runFasta($params, $data)->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 WSFasta service (http://www.ebi.ac.uk/Tools/webservices/services/fasta), 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”, “checkStatus” and “poll” work flow.

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

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

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

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

Soaplab (http://soaplab.sourceforge.net/) provides a framework for making analysis tools available via SOAP web services. The Soaplab server at EMBL-EBI (http://www.ebi.ac.uk/Tools/webservices/soaplab/overview) provides the EMBOSS suite and a few additional tools. Soaplab generic services use a similar work flow to that used in the WSFasta service, however the method names are slightly different:

1. createAndRun(params): to submit the job
2. getStatus(jobId): to check job status
3. getResults(jobId): to get the set of results

Using the Soaplab example (examples/SOAP/SOAP-Lite/soaplab_seqret_soaplite.pl) as a guide, use the Soaplab EMBOSS tmap service (http://www.ebi.ac.uk/soaplab/services/protein_2d_structure.tmap?wsdl) to find the transmembrane domains in UniProtKB entry CFTR_HUMAN.

Sample solution: solutions/SOAP/SOAP-Lite/q6_soaplab_tmap_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 a 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.

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());

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.