As an alternative method to posting E-utility URLs as described in earlier chapters of this book, NCBI provides a web service for accessing the E-utilities using the Simple Object Access Protocol (SOAP). This web service accesses the same E-utility CGIs as do the standard URLs described earlier, and so in general all of the E-utility parameters described in Chapter 4 can be used with the web service as well, and the functions of the web service methods are the same as their CGI counterparts. The only exception to this is that there is no retmode parameter for EFetch, since all SOAP data are returned in XML.

At present the E-utility web service has been tested in the following development environments:

• C# and Visual Basic in MS Visual Studio 2008

• Java (Apache Axis2 version 1.5.2)

The web service should also work with older versions of Axis (Axis for Java version 1.4) and MS Visual Studio (MSVS 2005). Developers can also use other SOAP libraries and tools to access the web service, but some functions may not be available.

Please see the following pages for detailed information about using the E-utility web service in the following environments:

C# and MS Visual Studio 2008

Visual Basic and Visual Studio 2008

Java and Apache Axis 2

Version 2.0 of the E-utility web service provides access to all seven E-utilities (ESearch, ESummary, EFetch, ELink, EPost, EGQuery and ESpell). To create a SOAP client application, developers should use one or more of the WSDL files listed below or download WSDL/XSD files from our FTP site.

The most significant change is that the eFetch method has been removed from the eUtils.wsdl file. Developers should now use the database-specific WSDL file for EFetch to retrieve records from a database. For example, efetch_pubmed.wsdl should be used to retrieve records from PubMed.

The major changes in version 2.0 include the following:

• Removed the eFetch method from the eUtils.wsdl file and created new, separate WSDL for retrieving records in each database (e.g. efetch_pubmed.wsdl)

• Regenerated all schemas based on current DTDs (December 17, 2010)

• Fixed binding problems in WSDL files*

• Added support for EPost

• Eliminated mixed="true" from eSummary schema

• Added the linkname property in ELinkRequest elements

• Removed eUtils_lite.wsdl, efetch.wsdl, and efetch_lit.wsdl

Starting with version 2.0, new versions of the E-utility web service will be placed into separate directories. For example, version 2.0 is located in http://www.ncbi.nlm.nih.gov/entrez/eutils/soap/v2.0/.

Version 2.0 is not fully compatible with previous versions. Developers should regenerate their source code with the new WSDLs. The following should be done to update the project:

• Use eUtils.wsdl instead of eUtils_lite.wsdl

• Use eUtils_MS.wsdl if there are _MS methods called in the source code

• Use database-specific WSDL files instead of efetch.wsdl or efetch_lit.wsdl to retrieve records using EFetch; for example, efetch_pubmed.wsdl should be used to retrieve records from PubMed. To retrieve records from multiple databases, add a Web Reference for each database in MSVS. For Axis2, run WSDL2Java for each database and include the package in the project. Each database-specific WSDL file has a different namespace to prevent name conflicts.

(*) Methods with _MS suffix have been moved to the eUtils_MS.wsdl file, which should be used in MS Visual Studio only. Those methods require input parameters in a different format, i.e. a list of parameters in the method's definition instead of one object.

Please see the following tables for a list of class properties for each E-utility request. These properties apply for all supported development environments.

For general information about web services, please see this overview.

E-utility DTDs

Please see Chapter 1 for getting additional information about the E-utilities.