Web Services Part II

1
Web Services Part II

• EMBnet Course Advanced Programming for
  Biologists, EPFL
• 3 September 2009

Heinz Stockinger, Vital-IT, Lausanne
2
Outline

• Overview and Background
• Web and Internet Protocols
• Web services
• Programming Web Services with PHP

3
Goal for this lecture

• Start with the interface of a Web service (WSDL
  file) and create a PHP client
• Advanced steps
• Create service
• Interface design considerations

4
PHP.SOAP

• SOAP needs to be explicitly enabled in your PHP
  distribution
• For instance, compile PHP with --enable-soap
• Enable SOAP in Apache
• Documentation
• http//php.net/soap
• Recommended to use that in this course

5
Simple client - blast.php

• A minimal example using
• WSDL file as input
• SoapClient()
• Generates the request on the fly

lt? echo "Contact a BLAST service search for
DPILGVTEAYKRDTlt/brgt" client new
SoapClient('http//xml.nig.ac.jp/wsdl/Blast.wsdl')
result client-gtsearchSimple('blastp',
'SWISS,
'DPILGVTEAYKRDT') result
nl2br(result) echo result ?gt
6
SoapClient Constructor

• SoapClient(mixed wsdl ,array options)
• WSDL file or NULL if used in non-WSDL mode
• options (mandatory in non-WSDL mode)
• location URL of service
• uri URI of target namespace
• style document or RPC style
• SOAP_DOCUMENT, SOAP_RPC
• use literal or encoded
• SOAP_LITERAL, SOAP_ENCODED

7
Example constructor function call
WSDL file contains service URL etc.

• client new SoapClient(Blast.wsdl)
• client  new SoapClient(null, 
• array('location' gt "http//localhostsoap.php
  ",
•        'uri'      gt "http//test-uri/"))
• Function call two options
• client-gtSomeFunction(a, b, c)
• client-gt__soapCall("SomeFunction", 
• array(a, b, c))

OR
8
fetchDB example - fetchDB.php

• lt?
• echo "Contact a fetchDB service for
  UniProtVAV_HUMAN lt/brgt"
• client new SoapClient('http//www.ebi.ac.uk/T
  ools/webservices/wsdl/WSDbfetch.wsdl')
• result client-gtfetchData('UniProtVAV_HUMAN'
  , 'default', 'default')
• result nl2br(result)
• echo result
• ?gt

9
Development and debugging hints

• client-gt__getFunctions()
• Get all functions implemented by the remote
  service
• print_r(var)
• Print contents of the variable in human-readable
  format
• var_dump(var)
• Dumps contents of a variable (includes data
  types)

10
Running example FuncNet Service

• Protein prediction service (http//funcnet.eu)
• http//funcnet.eu/soap/FrontEnd.wsdl
• Input two protein sets (query and reference)
• Output raw scores and p-values for each tuple

11
(No Transcript)
12
FuncNet in soapUI client
13
FuncNet SOAP Request Example
ltsoapenvEnvelope xmlnssoapenv"http//schemas.xm
lsoap.org/soap/envelope/"
xmlnsfun"http//funcnet.eu/FuncNet_1_1
/"gt ltsoapenvHeader/gt ltsoapenvBodygt
ltfunSubmitTwoProteinSetsgt
ltqueryProteinsgt ltpgtP12345lt/pgt
ltpgtP12346lt/pgt ltpgtP12347lt/pgt
lt/queryProteinsgt ltrefProteinsgt
ltpgtP12348lt/pgt ltpgtP12349lt/pgt
ltpgtP12355lt/pgt lt/refProteinsgt
ltemailAddressgtHeinz.Stockinger_at_isb-sib.chlt/emailAd
dressgt ltenableEmailNotifygttruelt/enableEma
ilNotifygt lt/funSubmitTwoProteinSetsgt
lt/soapenvBodygt lt/soapenvEnvelopegt
14
Before we look at code details

• FuncNet (as well as many other services)
  requires sets, i.e. arrays or complex data types
• Note arrays are rather complicated in SOAP
  since they can be interpreted in different ways
  by different programming languages

15
Reminder arrays in PHP (1)

• General syntax array(key gt values)
• Like in a database key (index) needs to be
  unique!
• If no key/index is provided, integer values are
  used
• Examples

Array ( 0 gt 1 1 gt 2 2 gt 3
3 gt 4 )
No index used, only values simpleArray
array(1,2,3,4) print_r(simpleArray)
PHP documentation also uses the term index to
refer to key
16
Reminder arrays in PHP (2)
Array ( day1 gt Mon day2 gt Tue
day3 gt Wed )
days array("day1" gt "Mon",
"day2" gt "Tue", "day3" gt
"Wed") print_r(days)
Array of arrays s1array("p1"gt"P12345",
"p2"gt"P12348", "rs"gt"3.2233",
"pv"gt"0.7222") s2array("p1"gt"P12345",
"p2"gt"P12349", "rs"gt"2.3345",
"pv"gt"0.8443") result array("s"gtarray(s1,
s2), "status"gt"OK")
17
Question how to a create protein set?
set array("p" gt "P12345", "p" gt
"P12346", "p" gt "P12347")
What is content of the variable set?
18
Two different ways to create a protein set
Preferred version for SOAP
19
ltfunSubmitTwoProteinSetsgt
ltqueryProteinsgt ltpgtP12345lt/pgt
ltpgtP12346lt/pgt ltpgtP12347lt/pgt
lt/queryProteinsgt ltrefProteinsgt
ltpgtP12348lt/pgt ltpgtP12349lt/pgt
ltpgtP12355lt/pgt lt/refProteinsgt
ltemailAddressgtHeinz.Stockinger_at_isb-sib.chlt/emailAd
dressgt ltenableEmailNotifygttruelt/enableEma
ilNotifygt lt/funSubmitTwoProteinSetsgt
set1 array("p" gt array('P12345', 'P12346',
'P12347')) set2 array("p" gt array('P12348',
'P12349', 'P12355')) paramsarray("queryProteins
" gt set1, "refProteins" gt
set2, "emailAddress"gt"Heinz.Stocki
nger_at_isb-sib.ch",
"enableEmailNotify" gt "true")
20
Full FuncNet request in PHP funcnet1.php
lt? client new SoapClient('FrontEnd.wsdl') se
t1 array("p" gt array('P12345', 'P12346',
'P12347')) set2 array("p" gt array('P12348',
'P12349', 'P12355')) paramsarray("queryProteins
" gt set1, "refProteins" gt
set2, "emailAddress"gt"Heinz.Stocki
nger_at_isb-sib.ch",
"enableEmailNotify" gt "true") result
client-gtSubmitTwoProteinSets(params) print_r(r
esult) ?gt
stdClass Object ( jobID gt
caffdubya/-1245541227e0eebda-7409 )
21
Result Object in funcnet1.php
result client-gtSubmitTwoProteinSets(params)
stdClass Object ( jobID gt
caffdubya/-1245541227e0eebda-7409 )
echo result
echo result-gtjobID
22
Another example with Object
stdClass Object ( s gt Array ( 0 gt
stdClass Object ( p1 gt P12345
p2 gt P12348
rs gt 2.0000010000582E-6 pv
gt 0.999999 pr gt stdClass
Object ( rs gt 0
pv gt 0.999999
i gt 6 )
)
How to access the value of the variable pv?
23
SOAP Fault

• In case of errors, SOAP can create Faults
• Equivalent to exceptions in languages such as Java

try result client-gtSubmitTwoProteinSets(p
arams) print_r(result) catch (SoapFault
fault) trigger_error("SOAP Fault(faultcode
fault-gtfaultcode,
faultstring fault-gtfaultstring)",
E_USER_ERROR)
Filename funcnet2.php
24
Synchronous vs. asynchronous service

• Explain difference in class
• Asynchronous service (mentioned in lecture)
• FuncNet FrontEnd service
• monitorJob
• retrievePairwiseScores
• retrieveCompleteScores
• Synchronous services (mentioned in lecture)
• BLAST
• fetchDB

25
Lets now look at the server side
26
SOAP Server

• We now want to write a SOAP server for our
  FuncNet service for the method
• SubmitTwoProteinSets
• Required steps
• Adapt WSDL file (service part)
• Specify server URL port (optional)
• Need to write a server that accepts requests
• Implement the method SubmitTwoProteinSets

27
SOAP Server 1. Adapt WSDL file

• Make a copy of the file FrontEnd.wsdl and call it
  FrontEnd-local.wsdl
• Change the URL to e.g.

ltsoapaddress location"http//localhost/server-f
uncnet.php" /gt
28
SOAP Server 2. Implement Server
lt?php function SubmitTwoProteinSets(parms)
// some more code here return
array("jobID"gt"jobid-12345") ini_set("soap.ws
dl_cache_enabled", "0") server new
SoapServer("FrontEnd-local.wsdl") server-gtaddFun
ction("SubmitTwoProteinSets") server-gthandle()
?gt
Filename funcnet-server.php as specified in WSDL
file.
29
WSDL interface design Some remarks

• How to create a WSDL file from scratch?
• Certain tools allow to generate WSDL files from
  programming language interfaces
• java2wsdl
• php2wsdl
• However, these tools do not always work 100
  satisfactory
• Often, manual intervention or complete manual
  design is recommended
• Then, other tools can be used to check if the
  WSDL file is correct

30
Conclusion

• SOAP needs to be explicitly enabled in your PHP
  distribution
• Typically, start from WSDL file to generate
  client and/or server
• Reverse engineer data types for
  request/response
• There are some prototype tools to automatically
  generate PHP code from WSDL (wsdl2php)
• SOAP services can be accessed by different
  programming languages
• Reminder they are based on Internet protocols
• We only discussed PHP implementations