Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
dev:web_services [2008/06/10 07:31] ishan |
— (current) | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== Web Services ====== | ||
- | Right now the web services are exposed as SOAP. Work is underway to support REST. The NuSoap library is used,but it does not support the entire WS* stack. Thus HTTP Basic authentication is used. Research is underway in to the recently released WSF/PHP SOAP library( released last month). Its the only library that supports the entire WS* stack. | ||
- | |||
- | ===== SAHANA web services requirements ===== | ||
- | |||
- | |||
- | - In the admin section, you can turn off authentication for web services. Thus if you turn off authentication here is sample code to access the web service. | ||
- | <code php> | ||
- | <?php | ||
- | // Pull in the NuSOAP code | ||
- | require_once(' | ||
- | |||
- | $url=' | ||
- | //make sure you specify the URL of the Sahana server, you installed | ||
- | $client = new soapclient($url); | ||
- | |||
- | // Check for an error | ||
- | $err = $client-> | ||
- | if ($err) { | ||
- | // Display the error | ||
- | echo '< | ||
- | // At this point, you know the call that follows will fail | ||
- | } | ||
- | // Call the SOAP method | ||
- | $result = $client-> | ||
- | ?> | ||
- | |||
- | </ | ||
- | - If authentication is required, please read this section | ||
- | |||
- | Since i wanted to authenticate based on the following policy, had to use the basic authentication | ||
- | |||
- | Policy: In the process of signing up for the API key the following are issued | ||
- | |||
- | - API key | ||
- | - Password | ||
- | - Secret Code | ||
- | |||
- | API key and Password helps to identify the user. How ever, since these are transmitted in plain text needed something additional to prevent impersonation.Thus a digest is signed using HMAC_Sha1 algorithm and this signature is sent in the basic authentication. | ||
- | |||
- | Here is the complete client code when authentication is required at the server. | ||
- | |||
- | <code php> | ||
- | <?php | ||
- | // Pull in the NuSOAP code | ||
- | require_once(' | ||
- | $digest=" | ||
- | $secret=" | ||
- | // replace with the secret you obtain when you sign up for the Key | ||
- | $sign=_sahana_hmac_sha1($digest, | ||
- | $sign=md5($sign); | ||
- | $url=' | ||
- | //make sure you specify the URL of the Sahana server, you installed | ||
- | $client = new soapclient($url); | ||
- | $api_key=””;// | ||
- | $pwd=””;// | ||
- | $arg1=trim($api_key."," | ||
- | $client-> | ||
- | // Check for an error | ||
- | $err = $client-> | ||
- | if ($err) { | ||
- | // Display the error | ||
- | echo '< | ||
- | // At this point, you know the call that follows will fail | ||
- | } | ||
- | // Call the SOAP method | ||
- | $result = $client-> | ||
- | |||
- | function _sahana_hmac_sha1($data, | ||
- | if(($data==null)or($key==null)){ | ||
- | return null; | ||
- | } | ||
- | $blocksize = 64; | ||
- | $hashfunc = ' | ||
- | |||
- | if (strlen($key) > $blocksize) { | ||
- | $key = pack(' | ||
- | } | ||
- | |||
- | $key = str_pad($key, | ||
- | $ipad = str_repeat(chr(0x36), | ||
- | $opad = str_repeat(chr(0x5c), | ||
- | $hmac = pack( | ||
- | ' | ||
- | ($key^$opad).pack( | ||
- | ' | ||
- | ($key^$ipad).$data | ||
- | ) | ||
- | ) | ||
- | ) | ||
- | ); | ||
- | return $hmac; | ||
- | } | ||
- | |||
- | ?> | ||
- | </ | ||
- | |||
- | |||
- | Module developers can expose their functions using Sahana Web Services module. Developers needs to create two files to to their module directory. | ||
- | |||
- | - api.inc | ||
- | - ws.xml | ||
- | |||
- | |||
- | ==== api.inc ==== | ||
- | |||
- | |||
- | In this file, developers can define functions that are expected to expose as Web Services. | ||
- | |||
- | e.g. | ||
- | |||
- | <code php> | ||
- | /**. | ||
- | *This function return all the catalog names | ||
- | * @access public | ||
- | * @return array | ||
- | */ | ||
- | function shn_cs_get_all_catalog_names() | ||
- | { | ||
- | global $global; | ||
- | $db=$global[" | ||
- | $query=" | ||
- | $res=$db-> | ||
- | $unit_name_arr = array(); | ||
- | |||
- | while(!$res==NULL && !$res-> | ||
- | { | ||
- | $catalog_list[] = array(' | ||
- | $res-> | ||
- | } | ||
- | | ||
- | return $catalog_list; | ||
- | } | ||
- | </ | ||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | ==== ws.xml ==== | ||
- | |||
- | This file is used by the WS module to identify exposed services and their input/ | ||
- | |||
- | e.g. | ||
- | <code xml> | ||
- | <?xml version=" | ||
- | < | ||
- | < | ||
- | < | ||
- | < | ||
- | demo function | ||
- | </ | ||
- | < | ||
- | < | ||
- | shn_demo_function | ||
- | </ | ||
- | < | ||
- | < | ||
- | < | ||
- | </ | ||
- | < | ||
- | | ||
- | < | ||
- | A demo function | ||
- | </ | ||
- | </ | ||
- | < | ||
- | <!-- another service definition goes here --> | ||
- | </ | ||
- | </ | ||
- | </ | ||
- | </ | ||
- | |||
- | According to the parameter list (that lies beween " | ||
- | |||
- | E.g. | ||
- | |||
- | In above example there are two params. So there will be two text boxes will be populated in the client interface to get parameter values. | ||
- | |||
- | |||
- | If Developer needs to have his/her own Client interface, he or she can write a function in his/her api.inc in the following format. | ||
- | |||
- | <code php> | ||
- | function shn_< | ||
- | </ | ||
- | |||
- | e.g. If developer needs to have his/her own client interface in Synchronization module then he/she can write that client interface in following function. | ||
- | |||
- | <code php> | ||
- | |||
- | function shn_sync_ws_default(){ | ||
- | //your code here (client interface) | ||
- | } | ||
- | </ | ||
- | |||
- | **Important - Also developer needs to add special XML tag called < |