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.

1. 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.

<?php
// Pull in the NuSOAP code
require_once('nusoap.php');
 
$url='http://localhost/trunk/index.php?stream=soap&act=reg&wbsmod=or&mod=ws';
//make sure you specify the URL of the Sahana server, you installed
$client = new soapclient($url);
 
// Check for an error
$err = $client->getError();
if ($err) {
    // Display the error
    echo '<h2>Constructor error</h2><pre>' . $err . '</pre>';
    // At this point, you know the call that follows will fail
}
// Call the SOAP method
$result = $client->call('shn_or_type_list', array('name' => 'Ravindra'));
?>

1. If authentication is required, please read this section

Since i wanted to authenticate based on the following policy, had to use the basic authentication credentials in an alternative way. I used this policy ,since just user name and password sent as plain text for basic authentication is very insecure.

Policy: In the process of signing up for the API key the following are issued

1. API key

1. Password

1. Secret Code

Module developers can expose their functions using Sahana Web Services module. Developers needs to create two files to to their module directory.

1. api.inc
2. ws.xml

In this file, developers can define functions that are expected to expose as Web Services.

e.g.

/**.
 *This function return all the catalog names
 * @access public
 * @return array
 */
function shn_cs_get_all_catalog_names()
{
    global $global;
    $db=$global["db"];
    $query="SELECT ct_uuid,parentid,name FROM ct_catalogue";
    $res=$db->Execute($query);
    $unit_name_arr = array();
 
    while(!$res==NULL && !$res->EOF)
    {
    	$catalog_list[] = array('ct_id' => $res->fields["ct_uuid"], 'parent_id' => $res->fields["parentid"], 'name' => $res->fields["name"]);
    	$res->MoveNext();
    }
 
    return $catalog_list;
}

This file is used by the WS module to identify exposed services and their input/output types.

e.g.

<?xml version="1.0" encoding="ISO-8859-1"?>
<web_services>
	<services>
	 	<service>
	 		<name>
	 			List items in all inventories with associated quantities.
	 		</name>
	 		<http_type>GET</http_type>
	 		<api_function>
	 			shn_ims_list_item_by_inventory
	 		</api_function>
	 		<input type="xsd:string">inventory</input>
	 		<output type="BasicArray" />
	 		<documentation>
	 			A useful method to retrieve a list items in an all or a particular inventory with associated quantities
	 		</documentation>
	  	</service>
	 	<service>
	 		<name>
	 			Item Details
	 		</name>
	 		<http_type>GET</http_type>
	 		<api_function>
	 			shn_ims_get_item_details
	 		</api_function>
	 		<input type="xsd:string">filter</input>
	 		<output type="BasicArray" />
	 		<documentation>
 			Give more details on particular item type. Which 
inventories it is located in, quantities and expiry
	 		</documentation>
	 	</service>
	 </services>
 </web_services>