WSDbfetch (SOAP)

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 dbfetch service. Like the CGI service a request can return a maximum of 200 entries.

For more information see:

• dbfetch web interface
• dbfetch REST service

Web services registry entries:

• BioCatalogue:
  • WSDbfetch (REST)
  • WSDbfetch (document/literal SOAP)
  • WSDfetch (RPC/encoded SOAP)
• CoWS: Search result
• Health 2.0 API
  • WSDbfetch (document/literal SOAP)
  • WSDbfetch (RPC/encoded SOAP)
• NeuroLex.org
  • WSDbfetch (REST)
  • WSDbfetch (RPC/encoded SOAP)
• seekda!
  • WSDbfetch (RPC/encoded SOAP)
  • WSDbfetch (Legacy RPC/encoded SOAP)

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.

For further details see WSDbfetch Clients.

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 a WSDL with additional semantic annotations from EDAM (using SAWSDL) is also available: http://www.ebi.ac.uk/ws/services/WSDbfetchDoclit?sawsdl. An alternative SAWSDL annotated using the Ontology for Biomedical Investigations (OBI) is available from the WS Annotations Group of Dr. Jessica Kissinger's Research Group, University of Georgia.
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.

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.

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.

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:

• DbfParamsException: input parameters failed to validate.

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.

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.

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.

Get a list of database names usable with WSDbfetch.

Arguments: none

Returns: an array of strings containing the database names.

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

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

Generic exception used for errors thrown by the WSDbfetch service.

Subclasses:

• DbfParamsException
• DbfConnException
• DbfNoEntryFoundException

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

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

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

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

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