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.
====== WSDbfetch (SOAP) ======

===== Description =====

WSDbfetch allows you to retrieve entries from various up-to-date biological databases using entry identifiers or accession numbers. This is equivalent to the CGI based [[http://www.ebi.ac.uk/cgi-bin/dbfetch|dbfetch]] service. Like the CGI service a request can return a maximum of 200 entries.

For more information see:
  * [[http://www.ebi.ac.uk/Tools/dbfetch/|dbfetch web interface]]
  * [[services:dbfetch_rest|dbfetch REST service]]

Web services registry entries:
  * [[http://www.biocatalogue.org/|BioCatalogue]]:
    * [[http://www.biocatalogue.org/services/1925|WSDbfetch (REST)]]
    * [[http://www.biocatalogue.org/services/2654|WSDbfetch (document/literal SOAP)]]
    * [[http://www.biocatalogue.org/services/2701|WSDfetch (RPC/encoded SOAP)]]
  * [[http://www.cowebservices.com/CoWS/|CoWS]]: [[http://www.cowebservices.com/CoWS/search/compareSearch.action?queryString=wsdbfetch&searchType=1|Search result]]
  * [[http://health2api.com/|Health 2.0 API]]
    * [[http://health2api.com/?p=9598|WSDbfetch (document/literal SOAP)]]
    * [[http://health2api.com/?p=9552|WSDbfetch (RPC/encoded SOAP)]]
  * [[http://neurolex.org/|NeuroLex.org]]
    * [[http://neurolex.org/wiki/Category:Resource:EBI_Dbfetch|WSDbfetch (REST)]]
    * [[http://neurolex.org/wiki/Category:Resource:WSDbfetch_%28SOAP%29|WSDbfetch (RPC/encoded SOAP)]]
  * [[http://webservices.seekda.com/|seekda!]]
    * [[http://webservices.seekda.com/providers/ebi.ac.uk/WSDBFetchServerService|WSDbfetch (RPC/encoded SOAP)]]
    * [[http://webservices.seekda.com/providers/ebi.ac.uk/WSDBFetchServerLegacyService|WSDbfetch (Legacy RPC/encoded SOAP)]]

===== Clients =====

Sample clients are provided for a number of programming languages. For details of how to use these clients, download the client and run the program without any arguments.

==== WSDbfetch document/literal SOAP ====

^ Language ^ Download ^ Requirements ^
^ C# | .NET Executable: ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/csharp/bin/WSDbfetchCliClient.exe|WSDbfetchCliClient.exe]]'';\\ Source: ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/csharp/EBIWS2_CSharp/EbiWS/WSDbfetchClient.cs|WSDbfetchClient.cs]]'', ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/csharp/EBIWS2_CSharp/WSDbfetchCliClient/WSDbfetchCliClient.cs|WSDbfetchCliClient.cs]]'' | A .NET runtime environment. If building from source development tools are also required. See the [[tutorials:06_Programming:dot_net|.NET tutorial]] for details. |
^ Java | Executable jar: ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/jar/WSDbfetch_Axis1.jar|WSDbfetch_Axis1.jar]]'';\\ Source: ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/src/uk/ac/ebi/webservices/axis1/WSDbfetchClient.java|WSDbfetchClient.java]]'' | [[:tutorials:06_Programming:Java:SOAP:Apache Axis]]; All dependencies, including [[http://ws.apache.org/axis/|Axis 1.4]] and [[http://commons.apache.org/cli/|Commons-CLI]], are available in ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/jar/ebiws-lib.zip|ebiws-lib.zip]]''. |
^ | Executable jar: ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/jar/WSDbfetch_JAXWS.jar|WSDbfetch_JAXWS.jar]]'';\\ Source: ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/src/uk/ac/ebi/webservices/jaxws/WSDbfetchClient.java|WSDbfetchClient.java]]'' | [[:tutorials:06_Programming:Java:SOAP:JAX-WS]]; Various dependencies, including [[http://commons.apache.org/cli/|Commons-CLI]], are available in ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/jar/ebiws-lib.zip|ebiws-lib.zip]]''. |
^ Perl | ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/perl/soaplite/wsdbfetch_soaplite.pl|wsdbfetch_soaplite.pl]]'' | [[:tutorials:06_Programming:Perl:SOAP:SOAP-Lite|SOAP::Lite]] |
^ | ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/perl/xmlcompile/wsdbfetch_xmlcompile.pl|wsdbfetch_xmlcompile.pl]]'' | [[:tutorials:06_Programming:Perl:SOAP:XML-Compile-SOAP|XML::Compile::SOAP]] |
^ PHP | ''[[https://svn.ebi.ac.uk/webservices/webservices-2.0/trunk/php/php_soap/wsdbfetch_lib_php_soap.php|wsdbfetch_lib_php_soap.php]]'', ''[[https://svn.ebi.ac.uk/webservices/webservices-2.0/trunk/php/php_soap/wsdbfetch_cli_php_soap.php|wsdbfetch_cli_php_soap.php]]'', ''[[https://svn.ebi.ac.uk/webservices/webservices-2.0/trunk/php/php_soap/wsdbfetch_web_php_soap.php|wsdbfetch_web_php_soap.php]]'' | [[:tutorials:06_Programming:PHP:SOAP:PHP-SOAP]] |
^ Python | ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/python/suds/wsdbfetch_suds.py|wsdbfetch_suds.py]]'' | [[:tutorials:06_Programming:Python:SOAP:suds]] |
^ Ruby | ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/ruby/soap4r/wsdbfetch_soap4r.rb|wsdbfetch_soap4r.rb]]'' | [[:tutorials:06_Programming:Ruby:SOAP:soap4r]] |
^ VB.NET | Source: ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/vb.net/EBIWS2_VB/EbiWS/WSDbfetchClient.vb|WSDbfetchClient.vb]]'', ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/vb.net/EBIWS2_VB/WSDbfetchCliClient/WSDbfetchCliClient.vb|WSDbfetchCliClient.vb]]'' | A .NET runtime with development tools to build from source, see the [[tutorials:06_Programming:dot_net|.NET tutorial]] for details. For a .NET executable see the C# client above. |

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

^ Language ^ Download ^ Requirements ^
^ C# | .NET Executable: ''[[http://www.ebi.ac.uk/Tools/webservices/downloads/csharp/bin/wsdbfetch.exe|wsdbfetch.exe]]'';\\ Source: ''[[http://www.ebi.ac.uk/Tools/webservices/downloads/csharp/src/wsdbfetch.cs|wsdbfetch.cs]]'' | A .NET runtime environment. If building from source development tools are also required. See the [[tutorials:06_Programming:dot_net|.NET tutorial]] for details. |
^ Java | Executable jar: ''[[http://www.ebi.ac.uk/Tools/webservices/downloads/java/bin/WSDbfetch.jar|WSDbfetch.jar]]'';\\ Source: ''[[http://www.ebi.ac.uk/Tools/webservices/downloads/java/src/uk/ac/ebi/webservices/WSDbfetchClient.java|WSDbfetchClient.java]]'' | [[:tutorials:06_Programming:Java:SOAP:Apache Axis]]; All dependencies, including [[http://ws.apache.org/axis/|Axis 1.4]] and [[http://commons.apache.org/cli/|Commons-CLI]], are available in ''[[http://www.ebi.ac.uk/Tools/webservices/downloads/java/lib-1.4.zip|lib-1.4.zip]]''. |
^ Perl | ''[[http://www.ebi.ac.uk/Tools/webservices/downloads/perl/soaplite/dbfetch.pl|dbfetch.pl]]'' | [[:tutorials:06_Programming:Perl:SOAP:SOAP-Lite|SOAP::Lite]] |
^ PHP | ''[[https://svn.ebi.ac.uk/webservices/webservices-1.0/trunk/clients/php/wsdbfetch_cli_nusoap.php|wsdbfetch_cli_nusoap.php]]'' | [[:tutorials:06_Programming:PHP:SOAP:nuSOAP]] |
^ | ''[[https://svn.ebi.ac.uk/webservices/webservices-1.0/trunk/clients/php/wsdbfetch_cli_pear_soap.php|wsdbfetch_cli_pear_soap.php]]'' | [[:tutorials:06_Programming:PHP:SOAP:PEAR SOAP]] |
^ | ''[[https://svn.ebi.ac.uk/webservices/webservices-1.0/trunk/clients/php/wsdbfetch_cli_php_soap.php|wsdbfetch_cli_php_soap.php]]'' | [[:tutorials:06_Programming:PHP:SOAP:PHP-SOAP]] |
^ Python | ''[[http://www.ebi.ac.uk/Tools/webservices/downloads/python/soappy_clients/wsdbfetch.py|wsdbfetch.py]]'' | [[:tutorials:06_Programming:Python:SOAP:SOAPpy]] |
^ | ''[[http://www.ebi.ac.uk/Tools/webservices/downloads/python/zsi_clients/wsdbfetch_zsi.py|wsdbfetch_zsi.py]]'' | [[:tutorials:06_Programming:Python:SOAP:ZSI]] |
^ Ruby | ''[[http://www.ebi.ac.uk/Tools/webservices/downloads/ruby/wsdbfetch.rb|wsdbfetch.rb]]'' | [[:tutorials:06_Programming:Ruby:SOAP:soap4r]] |
^ Taverna 1.x | [[http://www.myexperiment.org/workflows/209|EBI_dbfetch_fetchBatch]] | [[http://www.taverna.org.uk/|Taverna]] |
^  | [[http://www.myexperiment.org/workflows/237|EBI_dbfetch_UniParc]] | [[http://www.taverna.org.uk/|Taverna]] |
^ Triana | [[http://www.myexperiment.org/workflows/895|EBI_dbfetch_fetchBatch]] | [[http://www.trianacode.org/|Triana]] |
^  | [[http://www.myexperiment.org/workflows/894|EBI_dbfetch_fetchData]] | [[http://www.trianacode.org/|Triana]] |
^ VB.NET | .NET Executable: ''[[http://www.ebi.ac.uk/Tools/webservices/downloads/vb.net/wsdbfetch.exe|wsdbfetch.exe]]'';\\ Source: ''[[http://www.ebi.ac.uk/Tools/webservices/downloads/vb.net/wsdbfetch.vb|wsdbfetch.vb]]'' | A .NET runtime environment. If building from source development tools are also required. See the [[tutorials:06_Programming:dot_net|.NET tutorial]] for details. |

For further details see [[.:archive:WSDbfetch Clients]].

==== Workflows ====

In addition to these sample clients users have submitted workflows using these services to the [[http://www.myexperiment.org/|myExperiment]] workflow repository. See [[http://www.myexperiment.org/workflows?filter=WSDL_ENDPOINT%28"http%3A%2F%2Fwww.ebi.ac.uk%2FTools%2Fwebservices%2Fwsdl%2FWSDbfetch.wsdl"+OR+"http%3A%2F%2Fwww.ebi.ac.uk%2Fws%2Fservices%2FWSDbfetchDoclit%3Fwsdl"+OR+"http%3A%2F%2Fwww.ebi.ac.uk%2Fws%2Fservices%2FWSDbfetch%3Fwsdl"+OR+"http%3A%2F%2Fwww.ebi.ac.uk%2Fws%2Fservices%2Furn:Dbfetch%3Fwsdl"+OR+"http%3A%2F%2Fwww.ebi.ac.uk%2Fws%2Fservices%2FDbfetch%3Fwsdl"%29|workflows using the WSDbfetch Web Services]] for a list.

===== WSDL =====

There are three interfaces to the WSDbfetch (SOAP) service, each with its own [[http://www.w3.org/TR/wsdl|WSDL]]:
  - WSDBFetchDoclitServerService (document/literal): http://www.ebi.ac.uk/ws/services/WSDbfetchDoclit?wsdl\\ Recommended for development of new clients. For compatible SOAP tool-kits WSDLs with additional semantic annotations (using [[http://www.w3.org/TR/sawsdl/|SAWSDL]]) are available:
    * Annotated using [[http://edamontology.sourceforge.net/|EDAM]]: [[http://www.ebi.ac.uk/ws/services/WSDbfetchDoclit?sawsdl]]
    * Annotated using [[https://code.google.com/p/obi-webservice/|OBIws]]: [[http://mango.ctegd.uga.edu/jkissingLab/SWS/Wsannotation/resources/WSDbfetch.sawsdl]]. Provided by the [[http://mango.ctegd.uga.edu/jkissingLab/|Kissinger Research Group, University of Georgia]].
  - WSDBFetchServerService (RPC/encoded): http://www.ebi.ac.uk/ws/services/WSDbfetch?wsdl\\ Provided for compatibility with SOAP tool-kits which support only RPC/encoded SOAP services and for use by older clients.
  - WSDBFetchServerLegacyService (RPC/encoded): http://www.ebi.ac.uk/ws/services/urn:Dbfetch?wsdl\\ **Deprecated** provided solely for compatibility with old clients, please do not use for new development.

===== Service API =====

==== fetchBatch(db, ids, format, style) ====

Fetch a set of entries in a defined format and style.

**Arguments**:
  * ''db'': the name of the database to obtain the entries from. For example: ''"uniprotkb"''
  * ''query'': a string containing a comma separated list of entry identifiers. For example: ''"WAP_MOUSE,WAP_RAT"''
  * ''format'': the name of the format required. To get the default format for the database use the value ''"default"''.
  * ''style'': the name of the style required. To get the default style for the database use the value ''"default"''.

**Returns**:

The format of the response depends on the interface to the service used:
  * WSDBFetchServerService and WSDBFetchDoclitServerService: the entries as a string.
  * WSDBFetchServerLegacyService: an array of strings containing the entries. Generally this will contain only one item which contains the set of entries.

**Throws**:
  * [[#DbfConnException]]: an issue occurred connecting to the database. 
  * [[#DbfException]]: an issue occurred performing the query. 
  * [[#DbfParamsException]]: input parameters failed to validate.
  * [[#DbfNoEntryFoundException]]: no entries were found matching the parameters.
  * [[#InputException]]: missing or incorrectly formatted parameters.

==== fetchData(query, format, style) ====

Fetch an entry in a defined format and style.

**Arguments**:
  * ''query'': the entry identifier in //db:id// format. For example: ''"UniProtKB:WAP_RAT"''
  * ''format'': the name of the format required. To get the default format for the database use the value ''"default"''.
  * ''style'': the name of the style required. To get the default style for the database use the value ''"default"''.

**Returns**:

The format of the response depends on the interface to the service used:
  * WSDBFetchServerService and WSDBFetchDoclitServerService: the entries as a string.
  * WSDBFetchServerLegacyService: an array of strings containing the entries. Generally this will contain only one item which contains the set of entries.

**Throws**:
  * [[#DbfConnException]]: an issue occurred connecting to the database. 
  * [[#DbfException]]: an issue occurred performing the query. 
  * [[#DbfParamsException]]: input parameters failed to validate.
  * [[#DbfNoEntryFoundException]]: no entries were found matching the parameters.
  * [[#InputException]]: missing or incorrectly formatted parameters.

==== getDatabaseInfo(db) ====

Get details describing specific database, including the available data formats and result styles.

**Note**: WSDBFetchDoclitServerService (document/literal) only.

**Arguments**:
  * ''db'': database name to get details for. For example: ''"uniprotkb"''

**Returns**: a data structure describing the database:
  * **DatabaseInfo**: details of a database.
    * **aliasList**: list of other names for the database.
      * **alias**: alias for the database, can be used in requests.
    * **databaseTerms**: list of ontology terms describing the database. Typically from [[http://drcat.sourceforge.net/|DRCAT]], [[http://edamontology.sourceforge.net/|EDAM]] and/or [[http://www.ebi.ac.uk/miriam/|MIRIAM]].
      * **databaseTerm**: ontology term describing the database. May be represented as a //namespace:id// identifier or a URI.
    * **dataResourceInfoList**: list of data resources used to provide obtain data for this database.
      * **dataResourceInfo**: summary information decribing the data resource.
        * **href**: link to the data resource main page or documentation.
        * **name**: name for/of the data resource.
    * **defaultFormat**: name of the data format used as the default.
    * **description**: a short description of the database, suitable for use in help documentation.
    * **displayName**: name of the database to be displayed in user interfaces. Not to be used for retrieval.
    * **exampleIdentifiers**: a set of example identifiers for entries appearing in the database.
      * **accessionList**: list of example accession numbers.
        * **accession**: example accession number.
      * **entryVersionList**: list of example entry version identifiers.
        * **entryVersion**: example entry version identifier.
      * **idList**: list of example Ids.
        * **id**: example Id.
      * **nameList**: list of example entry names.
        * **name**: example entry name.
      * **sequenceVersionList**: list of sequence version identifiers.
        * **sequenceVersion**: sequence version identifier.
    * **formatInfoList**: list of detailed information describing the available data formats.
      * **formatInfo**: details of an available data format.
        * **aliases**: list of other names for this data format, can be used in requests.
          * **alias**: an alias for this data format.
        * **dataTerms**: list of ontology terms describing the content of the data format. Typically from [[http://edamontology.sourceforge.net/|EDAM]].
          * **dataTerm**: ontology term describing the content of the data format. May be represented as a namespace:id identifier or a URI.
        * **name**: name for the data format, used in requests.
        * **styleInfoList**: list of details of available result styles.
          * **styleInfo**: details of an available result style.
            * **mimeType**: MIME type for results in this format and style.
            * **name**: name of this result style, to be used in requests.
        * **syntaxTerms**: list of ontology terms describing the syntax of the data format. Typically from [[http://edamontology.sourceforge.net/|EDAM]].
          * **syntaxTerm**: ontology term describing the syntax of the format. May be represented as a namespace:id identifier or a URI.
    * **href**: URL to the main database site, for use in help or documentation.
    * **name**: Name for the database, used in requests.

**Throws**:
  * [[#DbfParamsException]]: input parameters failed to validate.

==== getDatabaseInfoList() ====

Get details of all available databases, includes details of the available data formats and result styles.

**Note**: WSDBFetchDoclitServerService (document/literal) only.

**Arguments**: //none//

**Returns**: a list of data structures describing the databases. See [[#getDatabaseInfo(db)]] for a description of the data structure.

==== getDbFormats(db) ====

Get a list of format names for a given database.

**Arguments**:
  * ''db'': database name to get available formats for. For example: ''"uniprotkb"''

**Returns**: an array of strings containing the format names.

**Throws**:
  * [[#DbfParamsException]]: input parameters failed to validate.

==== getFormatStyles(db, format) ====

Get a list of style names available for a given database and format.

**Arguments**:
  * ''db'': database name to get available styles for. For example: ''"uniprotkb"''
  * ''format'': the data format to get available styles for. For example: ''"fasta"''

**Returns**: an array of strings containing the style names.

**Throws**:
  * [[#DbfParamsException]]: input parameters failed to validate.

==== getSupportedDBs() ====

Get a list of database names usable with WSDbfetch.

**Arguments**: //none//

**Returns**: an array of strings containing the database names.

==== getSupportedFormats() ====

Get a list of database and format names usable with WSDbfetch.

**Deprecated**: use of [[#getDbFormats(db)]], [[#getDatabaseInfo(db)]] or [[#getDatabaseInfoList()]] is recommended.

**Arguments**: //none//

**Returns**: an array of strings containing the database and format names. For example:
<code>uniprotkb       default,fasta,uniprot,uniprotxml</code>

==== getSupportedStyles() ====

Get a list of database and style names usable with WSDbfetch.

**Deprecated**: use of [[#getFormatStyles(db, format)]], [[#getDatabaseInfo(db)]] or [[#getDatabaseInfoList()]] is recommended.

**Arguments**: //none//

**Returns**: an array of strings containing the database and style names. For example:
<code>uniprotkb       default,html,raw</code>

==== DbfException ====

Generic exception used for errors thrown by the WSDbfetch service.

**Subclasses**:
  * [[#DbfParamsException]]
  * [[#DbfConnException]]
  * [[#DbfNoEntryFoundException]]

==== DbfParamsException ====

Exception indicating that the input parameters failed to validate. The message contains specific information about the cause. For example:
  * <code>uk.ac.ebi.jdbfetch.exceptions.DbfParamsException: Database, wibble , not found!</code>
  * <code>uk.ac.ebi.jdbfetch.exceptions.DbfParamsException: No database found for the job:
Job: 
        Database name: wibble
        Style: raw
        Format: default
        IDs:    blah
</code>

**Parent class**: [[#DbfException]]

==== DbfConnException ====

Exception indicating that there was a problem contacting the database to retrieve the requested data. For example:
<code>uk.ac.ebi.jdbfetch.exceptions.DbfConnException: Unexpected error when opening stream on the URL, please contact support@ebi.ac.uk</code>

**Parent class**: [[#DbfException]]

==== DbfNoEntryFoundException ====

Exception indicating that no entries were found in the database which matches the request. For example:
<code>uk.ac.ebi.jdbfetch.exceptions.DbfNoEntryFoundException: No result found</code>

Common causes of the error include:
  * Invalid identifier used for the specified database. For example: EMBL-Bank does not contain entries with RefSeq identifiers (e.g. XM_002123246).
  * Use of an identifier which is not supported for the specified database. For example: the EMBL-Bank query used by WSDbfetch does not support sequence versions (e.g. L12345.1) instead the accession (e.g. L12345) should be used, or the archive database EMBL-SVA, which does support sequence versions, should be queried.

**Parent class**: [[#DbfException]]

==== InputException ====

Exception indicating that required parameters were not specified, or were in an incorrect format. For example:
  * <code>uk.ac.ebi.jdbfetch.ws.wsdbfetch.InputException: The 'query' argument doesn't contain ':'. Proper format= DBNAME:ID</code>
  * <code>uk.ac.ebi.jdbfetch.ws.wsdbfetch.InputException: No database found in the query</code>
  * <code>uk.ac.ebi.jdbfetch.ws.wsdbfetch.InputException: No ID found in the query</code>

===== Contact =====

If you have any questions, comments, if you plan to use this service as part of a course or for a high number of submissions, please contact us via [[http://www.ebi.ac.uk/support/index.php?query=WebServices|EBI Support]].
EMBL-EBI Web Services

EMBL-EBI

Services

Research

Training

Industry

About us
