SOAP/WSDL Interface to Consensuspathdb

SOAP/WSDL interface to ConsensusPathDB

Thomas Meinel, Konstantin Pentchev, Atanas Kamburov Manual version 1.01: May 6, 2009

Web service access

The Web service access to ConsensusPathDB is available through the WSDL file. The file is available and accessible at: http://cpdb.molgen.mpg.de/ws/CPDB.wsdl. All provided web service methods are originally defined and documented therein. They can be retrieved from there and are explained in the section ’web service methods’ of this manual.

Server description

The server of a web service is the endpoint for a request message access. It is the interface of the web service request and the database access. The server retrieves the database query result and returns the response message.

The ConsensusPathDB database access and web interface is constructed in Python. Therefore, the web service module in the web server environment is written in Python: The Zolera SOAP Infrastructure ZSI, http://pywebsvcs.sourceforge.net, is used for ConsensusPathDB because it can handle complex data types in contrast to SOAPpy.

The given WSDL file describes the provided methods (functions, operations; synonyms) of ConsensusPathDB in correspondence to existing database queries. The program wsdl2py has been used to generate two Python files automatically from the WSDL file, a class file and a data types file. A server script (endpoint) has been generated, which technically integrates the data structure of the messages (this is supported by the two files) with the database connection.

Hints for client generation

A WSDL ﬁle comprises all necessary information that must be published if a client shall be used, from accessing the server endpoint to the data structure of single methods. The Consen- susPathDB WSDL ﬁle is constructed using method parameters of type ’complexTypes’. This allows the serialization of two or more data arrays in a SOAP message, which is needed for sev- eral ConsensusPathDB methods. In those cases, the arrays have to be combined by individual programming in a respective client script.

A server should allow the access from diﬀerent types of platforms a client can reside. There are good experiences to use the Python ZSI environment, the Perl XML:Compile:WSDL11 environment, as well as the Taverna workﬂow management system. Other WSDL-supporting

1 modules like Python SOAPpy or Perl SOAP:Lite cannot regard complex data types and are therefore unable to support the ConsensusPathDB web service access. We provide examples of clients for single methods and platforms in a separate section of this documentation and in the Embrace Registry, http://www.embraceregistry.net/.

2 Web service methods

General methods

1 getDatabaseVersion Returns the current version and build date of ConsensusPathDB. parameter name data type input parameter (none) (none) output explanation current CPDB version parameter name data type output parameter CPDB version string example getDatabaseVersion() output 9 (08.01.2009) status: Perl-client: OK Python-client: OK

2 getSourceDatabaseVersions Returns a list of strings containing the versions of integrated source databases. parameter name data type input parameter (none) (none) output explanation two string arrays of integrated source databases and database versions parameter name data type output parameter 1 databases array of strings . . . new: database array of strings output parameter 2 versions array of strings . . . new: version array of strings example getSourceDatabaseVersions() output 1 Reactome; KEGG; HumanCyc; PID; . . . output 2 27; 49.0; 12.5; 2008 12 09; ... status: Perl-client: OK Python-client: OK

3 getNames Retrieves the names of any object in ConsensusPathDB given by its identifier. Different names correspond to the annotations in the source databases. input explanation any ConsensusPathDB entity identifier parameter name data type input parameter CPDB entityID integer output explanation annotation names parameter name data type output parameter entityNames array of strings . . . new: entityName array of strings example getNames(186) input 186 output ATP; Adenosine 5‘-triphosphate; adenylpyrophosphate; . . . status: Perl-client: OK Python-client: OK

3 4 getDBrefs Identifiers of external databases are integrated in ConsensusPathDB. This access method offers a retracing to the original resource annotation for a given ConsensusPathDB entity. input explanation any ConsensusPathDB entity identifier parameter name data type input parameter CPDB entityID integer output explanation annotation names parameter name data type output parameter 1 accType array of strings output parameter 2 acc array of strings . . . new: databaseKey array of strings . . . new: databaseID array of strings example getDBrefs(186) input 186 output 1 pubchem, kegg, reactome, . . . output 2 8143180, C00002, 29358; . . . status: Perl-client: OK Python-client: nonsense ID induces no error, but response message is not conform

4 Methods connected with an over-representation analysis

5 ORApathways ConsensusPathDB provides an over-representation analysis for entities in a pathway searching all pathways. Entities are handled to the method as a list of identiﬁers of a foreign database. Additionally, the the minimum overlap between pathway members and the input list (default: 2) is required as well as the respective database key (’hgnc’, ’uniprot’, ’ensembl’, . . . ). The result is a list of pathways that are found according the input parameters. It comprises the pathway name, the source database key of the pathway, all members of a pathway (by ConsensusPathDB ID), pathway members overlapping with the input (by ConsensusPathDB ID), the overall number of elements in the pathway, the number of overlapping members, and the p-value that is calculated with the hypergeo- metric distribution.

input explanation parameter name data type input parameter 1 CPDB idType string input parameter 2 CPDB idList array of strings . . . new: databaseKey string . . . new: databaseID array of strings input parameter 3 bol integer output explanation list of a list of seven parameters parameter name data type output parameter 1 pValue float output parameter 2 pathway string output parameter 3 database string . . . new databaseKey string output parameter 4 pathway members space-delimited string of identifiers . . . new pathwayMember space-delimited string of identifiers output parameter 5 membersInputOverlap space-delimited string of identifiers . . . new: overlapMember space-delimited string of identifiers output parameter 6 pathwaySize integer output parameter 7 overlapSize integer example ORApathways(hgnc;’EIF3A,TUBA3D’;1) (the first element list is here displayed, only) input hgnc input (EIF3A, TUBA3D) input 1 output 1, 1. element list 0.000001 output 2, 1. element list eukaryotic protein translation output 3, 1. element list BioCarta output 4, 1. element list 16819, 16835, 19134, 19234, . . . output 5, 1. element list 19234 output 6, 1. element list 18 output 7, 1. element list 1 status: list of all database keys ??? Perl-client: OK Python-client: nonsense ID induces no error, but response message is not conform

5 Workﬂows: combination of methods

The combination of methods elucidates the ConsensusPathDB database content, which is orga- nized in instances and explanations. Instances are pathways, interactions, or entities with the special cases of complexes, groups and interaction partners. They are represented by Consen- susPathDB identiﬁers. Explanations are given by names, references, entity types, or interaction types and consist of verbose terms or abbreviations.

queriable instances with retrieval methods instance queriable by method method names pathway 12 searchPathway interaction 8, 14 getInteractionsOfEntity, getInteractionsOfPathway entity 5, 13 searchEntity, getEntitiesOfPathway complex components 10 getComponentsOfComplex group members 11 getMembersOfGroupEntity interaction partners 7 queriable explanations with retrieval methods explanation queriable by method method names names 3 getNames references 4 getDBrefs type 6, 9 getEntityType, getInteractionType Presented methods perform the retrieval of instances and explanations, the combination of methods make the database query result human readable. Meaningful combinations, initially based on querying entities or pathways, are presented in the ﬁgure below.

6 Client scripts

Python clients using the ZSI module Prepare class ﬁle CPDB 1 04 services.py and types ﬁle CPDB 1 04 services types.py: unix/linux/console> wsdl2py -u http://cpdb.molgen.mpg.de/ws/CPDB.wsdl The handling of complex data types, array of arrays, in Python is performed by the zip function as given in method 15, ORApathways. 1. getDatabaseVersion

from CPDB 1 04 services import ∗ # including message tracing import sys kw = { ’tracefile’ : sys.stdout } methodLocator = CPDBLocator() .getCPDB portType (∗∗kw) # or without message tracing methodLocator = CPDBLocator() .getCPDB portType ( ) # Build the request request = getDatabaseVersionRequest() # Call the service response = methodLocator.getDatabaseVersion(request) # Extract the result result = response. CPDB version print r e s u l t

3. getNames

from CPDB 1 04 services import ∗ methodLocator = CPDBLocator() .getCPDB portType ( ) # Build the request request = getNamesRequest() r e q u e s t . CPDB entityID = 2010 # Call the service response = methodLocator.getNames(request) # Extract the result result = response. entityNames print r e s u l t

15. ORApathways

from CPDB 1 04 services import ∗ methodLocator = CPDBLocator() .getCPDB portType ( ) # Build the request request = ORApathwaysRequest() r e q u e s t . CPDB idType = ’hgnc’ r e q u e s t . CPDB idList = [ ’EIF3A’ , ’TUBA3D’] r e q u e s t . b o l = 1 # Call the service response = methodLocator.ORApathways(request) # Extract the result result = zip( response. pValue, response. pathway, response. database , response . pathway members, response. membersInputOverlap , response. pathwaySize , response. overlapSize ) print r e s u l t

7 Perl clients using the XML:Compile:WSDL11 module Pre-install the XML:Compile:WSDL11 module and dependencies. Final Perl scripts consist of the concatenated method-speciﬁc part and the appendix.

1. getDatabaseVersion

#!/usr/bin/perl use XML: : Compile : : WSDL11; use XML:: Compile :: Transport ::SOAPHTTP; use s t r i c t ; # −−−−−−−−−−−−−−−−−−−−−−−−−− # define the method parameters my $WSDL = ”http://cpdb.molgen.mpg.de/ws/CPDB.wsdl” ; my $method = ”getDatabaseVersion” ; my $methods{$method} = ”CPDB version” ; my %methodsTypes = ( getDatabaseVersion => ’ s c a l a r ’ ) ; my $ e r r o r = 0 ; my %arguments = ( ) ; # −−−−−−−−−−−−−−−−−−−−−−−−−−

3. getNames

#!/usr/bin/perl use XML: : Compile : : WSDL11; use XML:: Compile :: Transport ::SOAPHTTP; use s t r i c t ; # −−−−−−−−−−−−−−−−−−−−−−−−−− # define the method parameters my $WSDL = ”http://cpdb.molgen.mpg.de/ws/CPDB.wsdl” ; my $method = ”getNames” ; my $methods{$method} = ”entityNames” ; my %methodsTypes = ( getNames => ’ array ’ ) ; my $ e r r o r = 0 ; my @argname = ( ”CPDB entityID” ) ; my @arg =(2010) ; my %arguments ; $arguments {$argname[0] } = $arg [ 0 ] ; # −−−−−−−−−−−−−−−−−−−−−−−−−−

15. ORApathways

#!/usr/bin/perl use XML: : Compile : : WSDL11; use XML:: Compile :: Transport ::SOAPHTTP; use s t r i c t ; # −−−−−−−−−−−−−−−−−−−−−−−−−− # define the method parameters my $WSDL = ”http://cpdb.molgen.mpg.de/ws/CPDB.wsdl” ; my $method = ”ORApathways” ; my %methods ; @{$methods{$method}} = (”pValue”, ”pathway”, ”database”, ”pathway members” , ”membersInputOverlap”, ”pathwaySize”, ”overlapSize”) ; my %methodsTypes = ( ORApathways => ’arrayOfarray’ ); my $ e r r o r = 0 ; my @argname = qw/CPDB idType CPDB idList bol/ ;

8 my @arg = ( ”hgnc”, ”EIF3A TUBA3D”, 1 ) ; my %arguments ; $arguments {$argname[0] } = $arg [ 0 ] ; my @arg1 = s p l i t /\ s+/ , $arg[1] ; @{ $arguments {$argname[1] }} = @arg1 ; $arguments {$argname[2] } = $arg [ 2 ] ; # −−−−−−−−−−−−−−−−−−−−−−−−−−

Appendix: Perl snippet to send, receive, print, and validate the result

# −−−−−−−−−−−−−−−−−−−−−−−−−− # create the virtual data structure my $wsdl = XML: : LibXML−>new−>p a r s e f i l e ( $WSDL ) ; my $proxy = XML::Compile::WSDL11−>new($wsdl); my $request = $proxy−>compileClient($method); # −−−−−−−−−−−−−−−−−−−−−−−−−− # execute the messages my $op = $proxy−>operation($method); my $ c a l l = $op−>compileClient; my ( $result, $trace ) = $call −>( %arguments ); # −−−−−−−−−−−−−−−−−−−−−−−−−− # retrieve the result i f ( defined $ r e s u l t ) { my $KEY1 = ”” ; my $KEY2 = ”” ; my $scalarKeys2 = ”” ; foreach my $keys1 ( keys %{$ r e s u l t } ) { $KEY1 = $keys1 ; foreach my $keys2 ( keys %{${ $ r e s u l t }{ $keys1 }} ) { $KEY2 = $keys2 ; my $val2 = $result −>{$keys1}−>{$keys2 } ; $val2 =˜ s /\n$//g ; i f ( $methodsTypes{$method} eq ”arrayOfarray” ) { $scalarKeys2 = scalar @{ $val2 } ; } } } # −−−−−−−−−−−−−−−−−−−−−−−− # message tracing my $requestOut = $trace −>{h t t p r e q u e s t }{ c onte nt } ; my $responseOut = $trace −>{h t t p r e s p o n s e }{ c onte nt } ; # −−−−−−−−−−−−−−−−−−−−−−−− # prepare the result printing my $printResult = ”” ; i f ( $methodsTypes{$method} eq ”scalar” ) { $printResult .= ”\n” . ${ $ r e s u l t }{$KEY1}{$KEY2} .”\n” ; } e l s i f ( $methodsTypes{$method} eq ” array ” ) { $printResult .= ”\n” . join (”\n” , @{${ $ r e s u l t }{$KEY1}{$KEY2}} ).”\n” ; } e l s i f ( $methodsTypes{$method} eq ”arrayOfarray” ) { $printResult .= ”\n” ; for ( my $aa = 0 ; $aa < $scalarKeys2 ; $aa ++ ) { for ( my $bb = 0 ; $bb < scalar @{$methods{$method}} ; $bb ++ ) { $printResult .= ”\ t ” i f ( $bb > 0 ) ; $printResult .= ${ $ r e s u l t }{$KEY1}{ $methods{$method } [ $bb ] } [ $aa ] ; }

9 $printResult .= ”\n” ; } $printResult .= ”\n” ; } print STDERR $printResult ; # −−−−−−−−−−−−−−−−−−−−−−−− # validation i f (! exists ${ $ r e s u l t }{$KEY1} ) { print STDERR ”\t− Unexpected data for CPDB\n” ; $ e r r o r = 2 ; } else { print STDERR ”\t− CPDB WSDL OK\n” ; } } else { print STDERR ”\t− CPDB Web Service Failed \n” ; exit 1 ; } # −−−−−−−−−−−−−−−−−−−−−−−−−− # error code validation i f ( $error == 0 ) { print STDERR ”\t− Everything worked fine \n\n” ; exit $ e r r o r ; } else { print STDERR ”\t− Last error code : $error \n\n” ; exit $ e r r o r ; } # −−−−−−−−−−−−−−−−−−−−−−−−−−