Answers to frequently asked questions (FAQs) about EBI's Web Services.

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

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 EBI Web Services, then you will need to set-up an appropriate development environment for your chosen programming language and select an appropriate SOAP library.

A number of tutorials are provided covering most common programming languages:

• 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 clients pages for the service of interest (list). The clients page (e.g. InterProScan Clients) provides a list of clients and details of the pre-requisites.

For most services we provide command-line clients for Java and Perl. For a few selected services a number of other clients are also available (e.g. WSDbfetch). 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 EBI are limited to one sequence, or one set of sequences, per job. Thus if you wish to analyse multiple sequences you will have to submit multiple jobs. The simplest 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 use the following scripts:

• UNIX and UNIX-like environments: fsplit.sh
• MS Windows: fsplit.bat

These scripts require the csplit program. The csplit program is available as part of the GNU coreutils package, for MS Windows a pre-complied version is available: csplit.zip.

To following scripts illustrate how to submit the jobs:

• UNIX and UNIX-like environments: wsbatch.sh

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

To stay informed about changes to the EBI web services and scheduled maintenance we recommend:

1. Keep an eye on the News page. There are RSS news feeds associated with the page if you want to see changes in your news reader.
2. The ws-users mailing list. This is a low volume mailing list containing service announcements and notification of appropriate training events.

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.

The latest SOAP::Lite versions contain a number of changes that affect their compatibility with our services. We are looking into ways to get our services working with the new versions. In the meantime please use SOAP::Lite 0.60 which is known to work with our services.

The typical error message received if an incompatible version of SOAP::Lite is used is:

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.

The client stubs produced by Axis WSDL2Java are version specific. The supplied clients have been built using Axis 1.2, provided in lib.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.zip and did not uncompress the zip file in your current directory, you will need to specify the full path to the folder.

To iterate over different sequences, as Taverna has no “for” structures, you can do the following:

1) Create a nested workflow and open it for editing

2) In the nested workflow you need to create a workflow input called JobID, no outputs are required although you can create an output called JobID as well, it might make things more convenient later.

3) You need to put three things in the nested workflow:

a) The process that checks the status given an ID, link this with the JobID input

b) An operation (probably a beanshell) which takes the output from (a) and returns true if and only if the output means that there are some results available. So, if the status as a string from (a) is 'SUCCESS' when there are results you create a beanshell with a single string input called 'state' and a single string output called 'finished' and have the script as 'finished = (state.equals(“DONE”));', this will return 'true' if the status was DONEand false otherwise.

c) A 'Fail if false' operation linked to the output of (b)

4) In the nested workflow you must check the 'critical' checkbox for the 'Fail if false' processor. This means that if this fails (i.e. if the input is false) the entire nested workflow will fail.

5) In the top level workflow you now need to configure the retry behaviour for the nested workflow. Exactly what you put here depends a bit on how long you expect the job to take but I suggest keeping the backoff factor very close to 1.0 (or leaving it at 1.0, i.e. the delay between retries remains the same). Set the retry delay to 30000 for a 30 seconds interval and, say, 10 retries. This would mean the status would be polled for 5 minutes or until it succeeded.

6) Again in the top level workflow you'll need a process that gets the results from a completed job given the JobID. This process can only be allowed to run when the nested worklow created in (1) has succeeded, fortunately you can create a coordination link to it (right click on the processor, select 'coordinate from' and choose the nested workflow).

You'll obviously also need to pass in the JobID. If you previously added a 'pass through' JobID output to the nested workflow you don't need the coordination link, it's really a matter of personal preference which way you do it.

Although this may sound slightly long winded it's actually quite quick to do. Basically you're using Taverna's retry policy control to repeatedly poll the state, as Taverna will only retry something that failed you have to make any state other than 'results ready' into a failure condition which is what the nested workflow described above will do.

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 EBI Web Services can be used, see references.