ChEBI Web Services

1. Introduction

The main aim of ChEBI Web Services is to provide programmatic access to the ChEBI database in order to aid our users in integrating ChEBI into their applications. Web Services is an integration technology. To ensure software from various sources work well together, this technology is built on open standards such as Simple Object Access Protocol (SOAP), a messaging protocol for transporting information, Web Services Description Language (WSDL), a standard method of describing Web Services and their capabilities. For the transport layer itself, Web Services utilise most of the commonly available network protocols, especially Hypertext Transfer Protocol (HTTP).

ChEBI provides SOAP access to its database.

If you just wish to obtain light weight ontology objects you can use the Ontology Lookup Service as alternative Web Services.

2. Web Service Description Language (WSDL)

The ChEBI WSDL specifies the contract between external developers and the ChEBI Web Services. The Web Service Description Language (WSDL) is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information.

The ChEBI WSDL uses the Document/literal binding. A WSDL binding describes how the service is bound to a messaging protocol, particularly the SOAP messaging protocol.

3. Implementation Overview

The ChEBI Web Services contains four main operations with which developers can access data. An example invocation of the SOAP response can be seen by filling in the forms and submitting them. These forms are only for demonstration purposes and should not be used for any production purposes.

The JavaDoc for the ChEBI model used for the data can be accessed online.

getLiteEntity

Retrieves a list of "lite" entities containing only the ChEBI ASCII name and ChEBI identifier. The input parameters are a search string and a search category. If the search category is null then it will search under all fields. The search string accepts the wildcard character "%" and also unicode characters.

getCompleteEntity

Retrieves the complete entity including synonyms, database links and chemical structures, using the ChEBI identifier.

getOntologyParents

Retrieves the ontology parents of an entity including the relationship type, using the ChEBI identifier.

getOntologyChildren

Retrieves the ontology children of an entity including the relationship type, using the ChEBI identifier.

4. SOAP Clients

The ChEBI Web Services team has provided the clients in perl and Java to access data. If you want a more specific client please follow the tutorial on the EBI Web Services page.

1. Perl client

   
   These are accessible on the ChEBI Web Services clients page with four main files to download depending on the methods you would like to access. The clients were tested with SOAP::Lite version 0.67. Click on the Download icon to download the SOAP:Lite Perl client.
   
   
   
   Below is an example perl file accessing the getCompleteEntity method.
   
   

   #!/usr/bin/perl -w
   # SOAP::Lite version 0.67
   # Please note: ChEBI webservices uses document/literal binding
   
   use SOAP::Lite + trace => qw(debug);
   #use SOAP::Lite;
   
   # Setup service
   my $WSDL = 'http://www.ebi.ac.uk/webservices/chebi/webservice?wsdl';
   my $nameSpace = 'http://www.ebi.ac.uk/webservices/chebi';
   my $soap = SOAP::Lite
   -> uri($nameSpace)
   -> proxy($WSDL);
   
   # Setup method and parameters
   my $method = SOAP::Data->name('getCompleteEntity')
   ->attr({xmlns => $nameSpace});
   my @params = ( SOAP::Data->name(chebiId => 'CHEBI:15377'));
   
   # Call method
   my $som = $soap->call($method => @params);
   
   # Retrieve for example all ChEBI identifiers for the ontology parents
   @stuff = $som->valueof('//OntologyParents//chebiId');
   print @stuff;
   




2. Java client

   
   The Java client was generated using Java API for XML Web Services (JAX-WS) version 2.0. Java version 1.5+ is required to run the client. To run this client you should download the chebiWS-client-1.1.1.jar file and place it in your classpath. In addition you should download version 2.0 of JAX-WS and put its libraries in your classpath. The ChebiWebServiceClient object is automatically instantiated with a value that describes the location of the ChEBI Web Services WSDL and ChEBI namespace. At this moment these are located as follows:
   ChEBI WSDL: http://www.ebi.ac.uk/webservices/chebi/webservice?wsdl
   ChEBI namespace (QName) is: http://www.ebi.ac.uk/webservices/chebi
   
   

   The JavaDoc for the ChEBI model used for the data can be accessed online.

   Click on the Download icon to download the JAX-WS generated Java client.
   
   
   
   In the WSChebiJAX-WS.jar file an Example.java class can be found with example code. An example is provided for each method below.
   
   getLiteEntity
   
   import uk.ac.ebi.chebi.webapps.chebiWS.client.ChebiWebServiceClient;
import uk.ac.ebi.chebi.webapps.chebiWS.model.ChebiWebServiceFault_Exception;
import uk.ac.ebi.chebi.webapps.chebiWS.model.*;

public class Example {
  public static void getLiteEntityExample (){

    try {

      // Create client
      ChebiWebServiceClient client = new ChebiWebServiceClient();
      System.out.println("Invoking getLiteEntity");
      LiteEntityList entities = client.getLiteEntity("alpha%", SearchCategory.ALL);
      List<LiteEntity> resultList = entities.getListElement();
      for ( LiteEntity liteEntity : resultList ) {
        System.out.println("CHEBI ID: " + liteEntity.getChebiId());
      }

    } catch ( ChebiWebServiceFault_Exception e ) {
      System.err.println(e.getMessage());
    }
  }
}

getCompleteEntity
   
   import uk.ac.ebi.chebi.webapps.chebiWS.client.ChebiWebServiceClient;
import uk.ac.ebi.chebi.webapps.chebiWS.model.ChebiWebServiceFault_Exception;
import uk.ac.ebi.chebi.webapps.chebiWS.model.*;

public class Example {
  public static void getCompleteEntityExample (){

    try {

      // Create client
      ChebiWebServiceClient client = new ChebiWebServiceClient();
      System.out.println("Invoking getCompleteEntity");
      Entity entity = client.getCompleteEntity("CHEBI:15377");
      System.out.println("GetName: " + entity.getChebiAsciiName());
      List<DataItem> synonyms = entity.getSynonyms();
      // List all synonyms
      for ( DataItem dataItem : synonyms ) {
        System.out.println("synonyms: " + dataItem.getData());
      }

    } catch ( ChebiWebServiceFault_Exception e ) {
      System.err.println(e.getMessage());
    }
  }
}

getOntologyChildren
   
   import uk.ac.ebi.chebi.webapps.chebiWS.client.ChebiWebServiceClient;
import uk.ac.ebi.chebi.webapps.chebiWS.model.ChebiWebServiceFault_Exception;
import uk.ac.ebi.chebi.webapps.chebiWS.model.*;

public class Example {
  public static void getOntologyChildrenExample (){

    try {

      // Create client
      ChebiWebServiceClient client = new ChebiWebServiceClient();
      System.out.println("Invoking getOntologyChildren");
      OntologyDataItemList children = client.getOntologyChildren("CHEBI:15377");
      List<OntologyDataItem> childrenList = children.getListElement();
      for ( OntologyDataItem ontologyDataItem : childrenList ) {
        System.out.println("CHEBI ID: " + ontologyDataItem.getChebiId());
      }

    } catch ( ChebiWebServiceFault_Exception e ) {
      System.err.println(e.getMessage());
    }
  }
}

getOntologyParents
   
   import uk.ac.ebi.chebi.webapps.chebiWS.client.ChebiWebServiceClient;
import uk.ac.ebi.chebi.webapps.chebiWS.model.ChebiWebServiceFault_Exception;
import uk.ac.ebi.chebi.webapps.chebiWS.model.*;

public class Example {
  public static void getOntologyParentsExample (){

    try {

      // Create client
      ChebiWebServiceClient client = new ChebiWebServiceClient();
      System.out.println("Invoking getOntologyParents");
      OntologyDataItemList parents = client.getOntologyParents("CHEBI:15377");
      List<OntologyDataItem> parentList = parents.getListElement();
      for ( OntologyDataItem ontologyDataItem : parentList ) {
        System.out.println("CHEBI names: " + ontologyDataItem.getChebiName());
      }

    } catch ( ChebiWebServiceFault_Exception e ) {
      System.err.println(e.getMessage());
    }
  }
}



5. Use Cases / Code Examples

All functional groups in ChEBI are suffixed with the term group. There chemical structures use the asterisk to represent where the structure connects. Therefore they do not have an InChI or SMILES associated with them. In addition all groups in ChEBI have an eventual is_a relationship to the term groups (CHEBI:24433).

#!/usr/bin/perl -w
# SOAP::Lite version 0.67
# Please note: ChEBI webservices uses document/literal binding
# This little program extracts all functional groups and prints
# them out. It searches for the word group in the ChEBI name and
# then discards any results which do not have chemical structures.

#use SOAP::Lite + trace => qw(debug);
use SOAP::Lite;

# Setup service
my $WSDL = 'http://www.ebi.ac.uk/webservices/chebi/webservice?wsdl';
my $nameSpace = 'http://www.ebi.ac.uk/webservices/chebi';
my $soap = SOAP::Lite
-> uri($nameSpace)
-> proxy($WSDL);

# Setup getLiteEntity for searching
my $method = SOAP::Data->name('getLiteEntity')
->attr({xmlns => $nameSpace});

# Setup full method to later retrieve chemical structures
my $fullMethod = SOAP::Data->name('getCompleteEntity')
->attr({xmlns => $nameSpace});

# Setup parameters to search for group
my @params = ( SOAP::Data->name(search => 'group'),
SOAP::Data->name(searchCategory => 'CHEBI NAME'));

# Call getLiteEntity method
my $som = $soap->call($method => @params);

# Retrieve all the ChEBI identifiers to iterate through them
# and check the structures
@ids = $som->valueof('//ListElement//chebiId');

my $counter = 0;
foreach $var (@ids) {
# Setup params based on ChEBI id of array to retrieve
# the full entry
my @fullParams = ( SOAP::Data->name(chebiId => $var));
my $full = $soap->call($fullMethod => @fullParams);

# Extract any ChemicalStructures in the result
@strucs = $full->valueof('//ChemicalStructures//structure');

# Discard any chemical structures not present
# and print the ones which are
if ($#strucs!=-1) {
$counter++;
print "$var is a functional group\n";
}

}

# print the number of functional groups found.
print "$counter functional groups found \n";

6. Announcements

1. Version

   
   The current version of the ChEBI Web Services is Version 1.1.1
   You can subscribe to all version announcements using the RSS feed below.
   
   

2. RSS

   
   All changes and new releases to the ChEBI Web Services will be announced on the ChEBI RSS Feed. Please subscribe by clicking on the RSS icon and copying the link into your RSS Reader.
   
   For more information on RSS feeds see our help file.

7. Suggestions

If the methods provided are not adequate for your applications please submit a request for the desired method on our Contact page or SourceForge forum. We are happy consider each request and extend the ChEBI Web Services as users see fit.