Answers to frequently asked questions (FAQs) about the Web Services provided by EMBL-EBI.

If you have a question that is not answered here please contact EMBL-EBI Support.

To stay informed about updates and changes to the EMBL-EBI Web Services, and scheduled maintenance to the EMBL-EBI website and services we suggest:

• Keep an eye on the Web Services News (RSS or Atom).
• Subscribe to the ws-users mailing list. This is a low volume mailing list containing service announcements and notification of appropriate training events.
• Follow emblebi and/or emblebies on Twitter.
• “Like” EMBL-EBI on Facebook.

This largely depends on how you want to use the services. There are two main categories of usage:

1. client development
2. existing clients

If you want to develop you own clients to the EMBL-EBI Web Services, then you will need to set-up an appropriate development environment for your chosen programming language and select an appropriate REST or SOAP took-kit.

A number of tutorials are provided covering most common programming languages and popular tool-kits:

• C/C++
• C#
• Java
• Perl
• PHP
• Python
• Ruby
• Visual Basic .NET

If you want to download a client and use the service right away then see the service documentation pages for the service of interest (list). The service page (e.g. InterProScan (SOAP)) provides a list of clients and details of the pre-requisites.

For most services we provide command-line clients for .NET, Java and Perl. For a few selected services a number of other clients are also available, for example:

• EB-eye
• InterProScan (REST)
• InterProScan (SOAP)
• NCBI BLAST (REST)
• NCBI BLAST (SOAP)
• WSDbfetch (REST)
• WSDbfetch (SOAP)

Which client you want to use depends on the platform. Currently we recommend using:

• MS Windows
  1. .NET client (where available)
  2. Java client
• MacOS X, Linux, UNIX and other UNIX-like systems
  1. Java client
  2. Perl client

If you have other processes using specific programming languages then you may wish to look at the corresponding client, where available.

If you want to download a client and get running with a service quickly, then see the clients page for the service of interest (list) for details of any existing clients.

If you want to develop you own clients, or services, you will need to choose a programming language and, if SOAP is not included with the language, a SOAP library. There are a wide selection of possibilities, some of the more common solutions are:

• C or C++ with Apache Axis or gSOAP
• Java with Apache Axis, JAX-RPC or JAX-WS
• .NET, Mono or Portable.NET (SOAP included), various languages including:
  • C#
  • Visual Basic
• Perl with SOAP::Lite or XML::Compile::SOAP
• PHP:
  • PHP 5 (SOAP included)
  • PHP 4 with nuSOAP
• Python with SOAPpy or ZSI
• R with RSOAP or Omegahat SSOAP
• Ruby with soap4r

Tutorials on using a selection of these languages and libraries can be found in the tutorials pages.

The Web Services provided by EMBL-EBI are limited to one sequence (e.g. the query sequence for a sequence similarity search), or one set of sequences (e.g. the set of sequences to be aligned for a multiple sequence alignment), per job. Thus if you wish to analyse multiple sequences you will have to submit multiple jobs.

Please note: We kindly ask all users to submit NO MORE THAN 25 JOBS AT THE TIME AND NOT TO SUBMIT MORE JOBS UNTIL YOU HAVE OBTAINED RESULTS FOR THE LAST 25. There are many people using these services and a fair share policy has been implemented that allows us to block users that submit jobs in a manner that prevents others from using the service. This block may affect access to the EMBL-EBI Web Services for an entire organisation or a class B or C subnet. Also make sure you USE A REAL EMAIL ADDRESS in your submissions. Using a fake email means we cannot contact you and will very likely result in your jobs being killed and your IP, Organisation or entire domain being black-listed. We do apologise for any inconvenience this may cause.

For some services the supplied clients support input of multiple sequences in the fasta sequence format. This has to be specifically enabled using a flag, see the client's help/usage information (typically accessed using the –help option) for details.

A simple way to do this is to create a set of files containing one sequence per file, and then loop over the files submitting each one, and getting the result.

To split a file containing multiple fasta formatted sequences into a set of files each containing a single sequence the following methods can be used:

• Use the EMBOSS seqretsplit program, part of EMBOSS, a collection of sequence manipulation and analysis tools.
• Use a script which uses the csplit utility. The csplit program is available as part of the GNU coreutils package, for MS Windows a pre-complied version is available: csplit.zip. See the following scripts for example usage:
  • UNIX and UNIX-like environments: fsplit.sh
  • MS Windows: fsplit.bat

To following scripts illustrate how to submit the jobs:

• UNIX and UNIX-like environments:
  • Dispatcher: wsbatch.sh
  • JDispatcher: jdispatcher_file_per-sequence_batch.sh

The following parallel job running tools may also be useful:

• GNU make
• GNU Parallel
• xjobs

Workflow systems (e.g. Kepler, Taverna or Triana) support a number of forms of automated bulk analysis. See Workflows and Web Services for further details.

Dedicated analysis tools, such as Blast2GO, may also use web services to provide some functionality or to perform a specific analysis. See their documentation for details.

Depending on your environment you may need to specify an HTTP proxy to access the Internet.

Perl, and many other scripting languages, read a set of environment variables to get the details of the available HTTP proxy. For UNIX and UNIX-like environments it is simplest to set these in your shell's start-up scripts.

C-shell (csh or tcsh) in ~/.login or ~/.cshrc:

setenv http_proxy 'http://proxy.example.org:8080'
setenv HTTP_proxy 'http://proxy.example.org:8080'
# For proxies requiring a username/password use:
#setenv http_proxy 'http://username:password@proxy.example.org:8080'
#setenv HTTP_proxy 'http://proxy.example.org:8080'
#setenv HTTP_proxy_user 'username'
#setenv HTTP_proxy_pass 'password'

Bourne shell (sh or bash) in .profile or .bashrc:

http_proxy='http://proxy.example.org:8080'
HTTP_proxy='http://proxy.example.org:8080'
export http_proxy HTTP_proxy
# For proxies requiring a username/password use:
#http_proxy='http://username:password@proxy.example.org:8080'
#HTTP_proxy='http://proxy.example.org:8080'
#HTTP_proxy_user='username'
#HTTP_proxy_pass='password'
#export http_proxy HTTP_proxy HTTP_proxy_user HTTP_proxy_pass

For SOAP::Lite you can also set the HTTP proxy directly, see the Perl tutorial for details.

If you cannot set the environment variables directly then you can set them from your Perl script. For example:

$ENV{'http_proxy'} = 'http://proxy.example.org:8080';
$ENV{'HTTP_proxy'} = 'http://proxy.example.org:8080';
# For proxies requiring a username/password use:
#$ENV{'http_proxy'} = 'http://username:password@proxy.example.org:8080';
#$ENV{'HTTP_proxy'} = 'http://proxy.example.org:8080';
#$ENV{'HTTP_proxy_user') = 'user'; # Proxy username (if required)
#$ENV{'HTTP_proxy_pass'} = 'password'; # Proxy password (if required)

See the documentation for the web tool kit being used for more details.

To use a HTTP proxy from Java you can set appropriate variables in your command line:

java -Dhttp.proxyHost=proxy.example.org -Dhttp.proxyPort=8080

If your proxy requires a username and password:

java -Dhttp.proxyHost=proxy.example.org -Dhttp.proxyPort=8080 -DproxyUser=username -DproxyPassword=password

We require a valid e-mail address so we can contact you in the event of:

• Problems with the service which affect your jobs.
• Scheduled maintenance which affects services you are using.
• Deprecation and retirement of a service you are using.

As described in our Terms of Use this information is not provided to anyone else, nor will we contact you except for the reasons stated above.

If you use a fake e-mail address then we will not be able to contact you and will very likely result in your jobs being killed and your IP, Organisation or entire domain being black-listed, see Terms of Use.

The standard Perl module installation routine:

perl Makefile.PL
make
make test
make install

assumes that your environment includes a version of the make program. While make is supplied with most UNIX and UNIX-like systems, it is not provided on MS Windows. A number of versions of make are available for MS Windows, the most widely used version being nmake. nmake is available as a download from the Microsoft website:

• nmake.exe

For details of how to install nmake for use with you Perl installation see http://johnbokma.com/perl/make-for-windows.html.

Various versions of SOAP::Lite contains bugs which cause compatibility issues with our services. Typical error messages indicating compatibility problems include:

• Can't find method element in the message at
  /ebi/extserv/bin/perl-5.8.3/lib/site_perl/5.8.3/SOAP/Lite.pm line 2311.

  This error is caused by using code developed for SOAP::Lite 0.60a (or eariler) with a later version of the library. As noted in the Perl tutorial, some services require that the parameters are passed in a slightly different way.

• Type 'inputParams' can't be found in a schema class 'SOAP::Serializer'

  Seen with SOAP::Lite releases 0.65, 0.66 and 0.68. These releases do not generate the required client code correctly from the WSDL and thus cannot encode complex types correctly.

• Can't bless non-reference value at WSPSIBlast.pm line 127.

  This is a server exception indicating that the contents of the message sent to the server could not be decoded correctly. Currently this has only been observed when using SOAP::Lite 0.710.10.

Current workarounds for these problems are:

1. Ensure you are using the current version of the Perl SOAP::Lite sample client for the service or that the client you are using includes code to ensure compatibility with SOAP::Lite 0.60a, 0.69 and 0.71.
2. Downgrade the version of SOAP::Lite to a version known to work with the services:
   • SOAP::Lite 0.60a
   • SOAP::Lite 0.69
   • SOAP::Lite 0.71 (SOAP-Lite-0.71.tar.gz)
   • SOAP::Lite 0.710.08

To determine the installed version of SOAP::Lite:

perl -e 'use SOAP::Lite; print $SOAP::Lite::VERSION, "\n";'

The client stubs produced by Axis WSDL2Java are version specific. The supplied clients have been built using Axis 1.4, provided in lib-1.4.zip. If you want to use a different version of Axis you will have to regenerate the stubs and re-compile, see the Java tutorial for further details.

This means that Java is not finding required classes. For example:

> java  WSEmbossClient
Exception in thread "main" java.lang.NoClassDefFoundError: WSEmbossClient

If the libraries and the current directory are not in the Java classpath use something like:

java -Djava.ext.dirs=lib -cp . WSEmbossClient

• -Djava.ext.dirs=lib adds the lib directory and any jars in the directory to the Java classpath
• -cp . adds the current directory to the Java classpath

If you are using the provided libraries from lib-1.4.zip and did not uncompress the zip file in your current directory, you will need to specify the full path to the folder.

Polling is implemented using the retry mechanism and a nested workflow. See Taverna tutorial: Polling for Results.

Example Taverna 1.x workflows for the EMBL-EBI services can be found in myExperiment.

In Taverna 2 the polling loop is handled as a property of the processor, rather then as an external workflow.

Example Taverna 2 workflows for the EMBL-EBI services can be found in myExperiment.

For a list of the database names used by dbfetch and the sequence similarity search services (e.g. WSFasta, WSNCBIBlast and WSWUBlast) see: Available databases.

Some of the services provide methods to get the details of the available databases at run time, see the page for the service for further details (list).

Depending on the service there may be a specific publication for the service which should be used, see the service documentation for details (list). If the service does not have a specific publication then one of the generic publications detailing the EMBL-EBI Web Services can be used, see references.