spacer
spacer

WSDbfetch (SOAP)

Description

WSDbfetch1) 2) 3) 4) 5) 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 dbfetch service6). Like the CGI service a request can return a maximum of 200 entries.

For more information see:

Web services registry entries:

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: WSDbfetchCliClient.exe;
Source: WSDbfetchClient.cs, WSDbfetchCliClient.cs
A .NET runtime environment. If building from source development tools are also required. See the .NET tutorial for details.
Java Executable jar: WSDbfetch_Axis1.jar;
Source: WSDbfetchClient.java
Apache Axis; All dependencies, including Axis 1.4 and Commons-CLI, are available in ebiws-lib.zip.
Executable jar: WSDbfetch_JAXWS.jar;
Source: WSDbfetchClient.java
JAX-WS; Various dependencies, including Commons-CLI, are available in ebiws-lib.zip.
Perl wsdbfetch_soaplite.pl SOAP::Lite
wsdbfetch_xmlcompile.pl XML::Compile::SOAP
PHP wsdbfetch_lib_php_soap.php, wsdbfetch_cli_php_soap.php, wsdbfetch_web_php_soap.php PHP-SOAP
Python wsdbfetch_suds.py suds
Ruby wsdbfetch_soap4r.rb soap4r
VB.NET Source: WSDbfetchClient.vb, WSDbfetchCliClient.vb A .NET runtime with development tools to build from source, see the .NET tutorial for details. For a .NET executable see the C# client above.

WSDbfetch RPC/encoded SOAP

Language Download Requirements
C# .NET Executable: wsdbfetch.exe;
Source: wsdbfetch.cs
A .NET runtime environment. If building from source development tools are also required. See the .NET tutorial for details.
Java Executable jar: WSDbfetch.jar;
Source: WSDbfetchClient.java
Apache Axis; All dependencies, including Axis 1.4 and Commons-CLI, are available in lib-1.4.zip.
Perl dbfetch.pl SOAP::Lite
PHP wsdbfetch_cli_nusoap.php nuSOAP
wsdbfetch_cli_pear_soap.php PEAR SOAP
wsdbfetch_cli_php_soap.php PHP-SOAP
Python wsdbfetch.py SOAPpy
wsdbfetch_zsi.py ZSI
Ruby wsdbfetch.rb soap4r
Taverna 1.x EBI_dbfetch_fetchBatch Taverna
EBI_dbfetch_UniParc Taverna
Triana EBI_dbfetch_fetchBatch Triana
EBI_dbfetch_fetchData Triana
VB.NET .NET Executable: wsdbfetch.exe;
Source: wsdbfetch.vb
A .NET runtime environment. If building from source development tools are also required. See the .NET tutorial for details.

For further details see WSDbfetch Clients.

Workflows

In addition to these sample clients users have submitted workflows using these services to the myExperiment workflow repository. See workflows using the WSDbfetch Web Services for a list.

WSDL

There are three interfaces to the WSDbfetch (SOAP) service, each with its own WSDL:

  1. 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 SAWSDL) are available:
  2. 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.
  3. 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:

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:

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 DRCAT, EDAM and/or 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 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 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:

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:

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:

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:

uniprotkb       default,fasta,uniprot,uniprotxml

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:

uniprotkb       default,html,raw

DbfException

Generic exception used for errors thrown by the WSDbfetch service.

Subclasses:

DbfParamsException

Exception indicating that the input parameters failed to validate. The message contains specific information about the cause. For example:

  • uk.ac.ebi.jdbfetch.exceptions.DbfParamsException: Database, wibble , not found!
  • uk.ac.ebi.jdbfetch.exceptions.DbfParamsException: No database found for the job:
    Job: 
            Database name: wibble
            Style: raw
            Format: default
            IDs:    blah
    

Parent class: DbfException

DbfConnException

Exception indicating that there was a problem contacting the database to retrieve the requested data. For example:

uk.ac.ebi.jdbfetch.exceptions.DbfConnException: Unexpected error when opening stream on the URL, please contact support@ebi.ac.uk

Parent class: DbfException

DbfNoEntryFoundException

Exception indicating that no entries were found in the database which matches the request. For example:

uk.ac.ebi.jdbfetch.exceptions.DbfNoEntryFoundException: No result found

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:

  • uk.ac.ebi.jdbfetch.ws.wsdbfetch.InputException: The 'query' argument doesn't contain ':'. Proper format= DBNAME:ID
  • uk.ac.ebi.jdbfetch.ws.wsdbfetch.InputException: No database found in the query
  • uk.ac.ebi.jdbfetch.ws.wsdbfetch.InputException: No ID found in the query

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 EMBL-EBI Support.

1) McWilliam H., Li W., Uludag M., Park Y.M., Buso N., Cowley A.P. and Lopez R. (2013)
Analysis Tool Web Services from the EMBL-EBI.
Nucleic Acids Research 41: W597-W600.
PubMed: 23671338
DOI: 10.1093/nar/gkt376
2) McWilliam H., Valentin F., Goujon M., Li W., Narayanasamy M., Martin J., Miyar T. and Lopez R. (2009)
Web services at the European Bioinformatics Institute - 2009.
Nucleic Acids Research 37: W6-W10.
PubMed: 19435877
DOI: 10.1093/nar/gkp302
3) Labarga A., Valentin F., Andersson M. and Lopez R. (2007)
Web Services at the European Bioinformatics Institute.
Nucleic Acids Research 35: W6-W11.
PubMed: 17576686
DOI: 10.1093/nar/gkm291
4) Labarga A., Pilai S., Valentin F., Anderson M. and Lopez R. (2005)
Web services at the European Bioinformatics Institute.
EMBnet.news 11(4):18-23.
5) Pillai S, Silventoinen V, Kallio K, Senger M, Sobhany S, Tate J, Velankar S, Golovin A, Henrick K, Rice P, Stoehr P and Lopez R. (2005)
SOAP-based services provided by the European Bioinformatics Institute.
Nucleic Acids Research 33:W25-8
PubMed: 15980463
DOI: 10.1093/nar/gki491
6) Harte N., Silventoinen V., Quevillon E., Robinson S., Kallio K., Fustero X., Patel P., Jokinen P. and Lopez R. (2004)
Public web-based services from the European Bioinformatics Institute.
Nucleic Acids Research 32: W3-W9.
PubMed: 15215339
DOI: 10.1093/nar/gkh405
 
services/dbfetch.txt · Last modified: 2014/02/24 16:15 by hpm
spacer
spacer