EMBL-EBI Web Services

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== SOAP::Lite ======

===== Installation =====

The SOAP::Lite modules can be installed by:
  - Using the system package manager install/update the appropriate package, for example libsoap-lite-perl for [[http://www.debian.org/|Debain]] based Linux systems (e.g. [[http://www.ubuntu.com/|Ubuntu]] or [[http://nebc.nox.ac.uk/tools/bio-linux/|Bio-Linux]])
  - Using CPAN to install/update SOAP::Lite ([[http://search.cpan.org/perldoc?SOAP::Lite|CPAN]]).
  - Downloading the SOAP::Lite distribution and installing manually:
    * from [[http://search.cpan.org/perldoc?SOAP::Lite|CPAN]]
    * from http://www.soaplite.com/
For an overview of the how to install a module see [[..:module_install|Installing Perl Modules]].

**Note**: check the version of SOAP::Lite before installing, there are [[:help:faq#Perl: I installed SOAP::Lite, but I get an error?|known issues]] with some versions.

===== Accessing a Service =====

There are three ways to use SOAP::Lite to access a SOAP Web Service:
  - Generate a dynamic interface to the service (service proxy) from a WSDL at runtime
  - Generate a static interface to the service (service proxy) from a WSDL
  - Directly invoke SOAP calls against the service

===== Dynamic Interface from a WSDL =====

==== SOAP::Lite->service($WSDL) ====

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 [[:services:dbfetch|WSDbfetch]] ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/examples/SOAP/SOAP-Lite/dbfetch_soaplite.pl|examples/SOAP/SOAP-Lite/dbfetch_soaplite.pl]])
<code perl>
# 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;
</code>

=== Exercise 1: WSDbfetch with SOAP::Lite ===

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

Using the example WSDbfetch client ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/examples/SOAP/SOAP-Lite/dbfetch_soaplite.pl|examples/SOAP/SOAP-Lite/dbfetch_soaplite.pl]]) as a guide, use the service to fetch the [[http://www.ebi.ac.uk/uniprot/|UniProtKB]] entries with the accessions: P13569, P26361 and P35071, in fasta format.

Sample solution: [[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/solutions/SOAP/SOAP-Lite/q1_dbfetch_soaplite.pl|solutions/SOAP/SOAP-Lite/q1_dbfetch_soaplite.pl]]

===== Static Interface from a WSDL =====

SOAP::Lite includes a utility (''stubmaker'' or ''stubmaker.pl'') to generate static code stubs from a WSDL document:
<code csh>stubmaker.pl http://www.ebi.ac.uk/ws/services/WSDbfetch?wsdl</code>
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 [[:services:dbfetch|WSDbfetch]] service ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/examples/SOAP/SOAP-Lite/dbfetch_soaplite_stubs.pl|examples/SOAP/SOAP-Lite/dbfetch_soaplite_stubs.pl]]):
<code perl>
# 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;
</code>

=== Exercise 2: Generate stubs ===

Generate static stubs for [[:services:dbfetch|WSDbfetch]] using ''stubmaker''. Check that the stubs have been generated successfully by running the stubs based client: [[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/examples/SOAP/SOAP-Lite/dbfetch_soaplite_stubs.pl|examples/SOAP/SOAP-Lite/dbfetch_soaplite_stubs.pl]].

=== Exercise 3: WSDbfetch meta-data ===

The [[:services:dbfetch|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 ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/examples/SOAP/SOAP-Lite/dbfetch_soaplite_stubs.pl|examples/SOAP/SOAP-Lite/dbfetch_soaplite_stubs.pl]]), use the ''getDbFormats()'' method of the [[:services:dbfetch|WSDbfetch]] service to determine what the available data formats are for the [[http://www.ebi.ac.uk/uniprot/|UniProtKB]] database.

Sample solution: [[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/solutions/SOAP/SOAP-Lite/q3_dbfetch_soaplite_stubs.pl|solutions/SOAP/SOAP-Lite/q3_dbfetch_soaplite_stubs.pl]]

===== Direct SOAP Calls =====

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 [[:services:dbfetch|WSDbfetch]] by performing direct calls ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/examples/SOAP/SOAP-Lite/dbfetch_soaplite_call.pl|examples/SOAP/SOAP-Lite/dbfetch_soaplite_call.pl]]):
<code perl>
# 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;
</code>

==== SOAP::Lite->uri()->proxy() ====

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 [[:services:eb-eye|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 ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/examples/SOAP/SOAP-Lite/ebeye_soaplite.pl|examples/SOAP/SOAP-Lite/ebeye_soaplite.pl]]):
<code perl>
# 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";
	}
}
</code>

==== Exercise 4: EB-eye ====

The [[:services:eb-eye|EB-eye web service]] ([[:services:eb-eye|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 ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/examples/SOAP/SOAP-Lite/ebeye_soaplite.pl|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: [[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/solutions/SOAP/SOAP-Lite/q4_ebeye_soaplite.pl|solutions/SOAP/SOAP-Lite/q4_ebeye_soaplite.pl]]

==== Exercise 5: EB-eye meta-data ====

Like [[:services:dbfetch|WSDbfetch]] the [[:services:eb-eye|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 ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/examples/SOAP/SOAP-Lite/ebeye_soaplite.pl|examples/SOAP/SOAP-Lite/ebeye_soaplite.pl]]) get the list of available domains (''listDomains()'') and the fields within these domains (''listFields(domain)'').

Sample solution: [[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/solutions/SOAP/SOAP-Lite/q5_ebeye_soaplite.pl|solutions/SOAP/SOAP-Lite/q5_ebeye_soaplite.pl]]

===== Complex Data Structures =====

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

Create the SOAP::Data objects to be passed to the service ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/examples/SOAP/SOAP-Lite/fasta_soaplite.pl|examples/SOAP/SOAP-Lite/fasta_soaplite.pl]]):
<code perl>
# 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";
</code>

See [[http://tardate.blogspot.com/2007/02/complex-soaplite-requests-my-rules-for.html|Complex SOAP::Lite requests - my rules for SOAP::Sanity!]] for a guide to building the complex structures required by some services.

=== Exercise 6: FASTA (SOAP) with SOAP::Lite ===

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 ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/examples/SOAP/SOAP-Lite/fasta_soaplite.pl|examples/SOAP/SOAP-Lite/fasta_soaplite.pl]]) and note the "run", "getStatus" and "getResult" work flow.

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

Sample solution: [[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/solutions/SOAP/SOAP-Lite/q6_fasta_soaplite.pl|solutions/SOAP/SOAP-Lite/q6_fasta_soaplite.pl]]

=== Exercise 7: FASTA (SOAP) meta-data ===

The [[:services:sss: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: [[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/solutions/SOAP/SOAP-Lite/q7_fasta_soaplite.pl|solutions/SOAP/SOAP-Lite/q7_fasta_soaplite.pl]]

===== SOAP Message Trace =====

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:
<code perl>SOAP::Lite->import(+trace => qw(debug));</code>

===== SOAP Faults =====

If a SOAP fault handler (''on_fault'') is not defined then faults must be checked for explicitly:
<code perl>
# Check for fault and map into an exception.
if($soap->call->fault) {
  die $soap->call->faultstring;
}
</code>

Normally the SOAP fault handler (''on_fault'') is used to map a faults to a ''die'' so normal Perl exception handling can be used:
<code perl>
# 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;
	}
);
</code>

===== HTTP Proxies =====

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:
  - Additional options to the ''SOAP::Lite->proxy()'' call. For example: <code perl>
my $soap = SOAP::Lite->proxy(
	$ENDPOINT,
	timeout => 6000,    # HTTP connection timeout
	proxy => ['http' => 'http://proxy.example.org/'] # HTTP proxy
  )->uri($NAMESPACE);
</code>
  - Setting information on the libwww-perl (LWP) object used for the HTTP transport. For example: <code perl>
$soap->transport->env_proxy(); # LWP to load proxy details from environment
</code>
See [[..:REST:LWP#Proxies]] for more details regarding LWP support for HTTP proxies.

===== HTTP User-Agent =====

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 [[http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43|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 [[http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.8|RFC2616 section 3.8]]) should be added to the beginning of the User-Agent string:
<code perl>
# 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());
</code>

**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.

===== HTTP Compression =====

SOAP::Lite provides support for on the fly compression of HTTP requests and decompression of HTTP responses ([[http://search.cpan.org/perldoc?SOAP::Lite#COMPRESSION|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:
<code perl>
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);
</code>

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.

===== Sample Clients =====

Most SOAP Web Services at [[http://www.ebi.ac.uk/|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.

==== Document/literal SOAP ====

^ Service ^ Sample client ^
| [[:services:EB-eye]] | [[http://www.ebi.ac.uk/Tools/webservices/download_clients/perl/soaplite/ebeye_soaplite.pl|ebeye_soaplite.pl]] |
| [[:services:pfa:iprscan_soap|InterProScan (SOAP)]] | [[http://www.ebi.ac.uk/Tools/webservices/download_clients/perl/soaplite/iprscan_soaplite.pl|iprscan_soaplite.pl]] |
| [[:services:sss:NCBI BLAST (SOAP)]] | [[http://www.ebi.ac.uk/Tools/webservices/download_clients/perl/soaplite/ncbiblast_soaplite.pl|ncbiblast_soaplite.pl]] |
| [[:services:dbfetch|WSDbfetch (SOAP)]] | [[http://www.ebi.ac.uk/Tools/webservices/download_clients/perl/soaplite/wsdbfetch_soaplite.pl|wsdbfetch_soaplite.pl]] |

==== RPC/encoded SOAP ====

^ Service ^ Sample client ^
| [[:services:dbfetch|WSDbfetch]] | [[http://www.ebi.ac.uk/Tools/webservices/downloads/perl/soaplite/dbfetch.pl|dbfetch.pl]] |
| [[:services:maxsprout|WSMaxsprout]] | [[http://www.ebi.ac.uk/Tools/webservices/downloads/perl/soaplite/maxsprout.pl|maxsprout.pl]] |

\\
^ Up | [[..:..:Perl]] ^ Contents | [[..:..:..:00_Contents|Contents]] |
EMBL-EBI Web Services

EMBL-EBI

Services

Research

Training

Industry

About us
