NATS4 API nusoap wsdlcache

When using the SOAP API, you can improve performance on API calls by caching the NATS wsdl file. This article shows an example of using the "nusoap_wsdlcache" to do so.

Including the nusoap_wsdlcache class

To use the "nusoap_wsdlcache" class, be sure to include it at the top of your script making the API calls. If you are using the TMM library version of nusoap, the wsdlcache class may already be included. This example shows how to check for the class before including the individual class file to prevent double inclusion.

<?
/* nusoap includes */
require_once('nusoap/lib/nusoap.php');
if(!class_exists("nusoap_wsdlcache")){ 
	require_once('nusoap/lib/class.wsdlcache.php');
}

Using the nusoap_wsdlcache class

The "nusoap_wsdlcache" class takes 2 parameters when declaring a new instance:

• Directory where cache files will be stored (<cache_dir> in example below)
• The time limit of the cache file in seconds (<wsdl_cache_lifetime> in example below)

To get the wsdl file for the first time, you must use an instance of the "wsdl" class. Since NATS protects the wsdl file, you must set the API login to get it using the wsdl class. The wsdl class has the same "setCredentials" function as the "nusoap_client" class.

//API login vars
$username = '<admin_username>'; // your admin username
$apikey = '<api_key>'; // your api key
$url = 'http://<your_nats_domain>/admin_api.php?wsdl'; // change <your_nats_domain>  to be domain of your NATS install

/* Nusoap WSDL cache setup */
//cache vars
$cache_dir = "<cache_dir>"; // change <cache_dir> to be the directory for storing cache files
$wsdl_cache_lifetime = <wsdl_cache_lifetime>; // change  <wsdl_cache_lifetime> to an amount in seconds

//construct cache
$wsdlCache = new nusoap_wsdlcache($cache_dir, $wsdl_cache_lifetime);

//try to get cache
$wsdl = $wsdlCache->get($url);
if (is_null($wsdl)) {
	//cache file not found, need to create new one
	$wsdl = new wsdl();
	$wsdl->setCredentials($username,$apikey);// need to login for NATS wsdl 
	$wsdl->fetchWSDL($url); //get the wsdl
	$wsdlCache->put($wsdl); //create cache file
}
$client = new nusoap_client($wsdl, TRUE);
//set your login for the soap client
$client->setCredentials($username,$apikey);
/* end Nusoap WSDL cache setup */

Full Example

This example code puts the pieces together to make a ping call.

<?php

/* Exmple API call using nusoap_wsdlcache class */
/* nusoap includes */
require_once('nusoap/lib/nusoap.php');
if(!class_exists("nusoap_wsdlcache")){ 
	require_once('nusoap/lib/class.wsdlcache.php');
}

//API login vars
$username = '<admin_username>'; // your admin username
$apikey = '<api_key>'; // your api key
$url = 'http://<your_nats_domain>/admin_api.php?wsdl'; // change <your_nats_domain>  to be domain of your NATS install

/* Nusoap WSDL cache setup */
//cache vars
$cache_dir = "<cache_dir>"; // change <cache_dir> to be the directory for storing cache files
$wsdl_cache_lifetime = <wsdl_cache_lifetime>; // change  <wsdl_cache_lifetime> to an amount in seconds

//construct cache
$wsdlCache = new nusoap_wsdlcache($cache_dir, $wsdl_cache_lifetime);

//try to get cache
$wsdl = $wsdlCache->get($url);
if (is_null($wsdl)) {
	//cache file not found, need to create new one
	$wsdl = new wsdl();
	$wsdl->setCredentials($username,$apikey);// need to login for NATS wsdl 
	$wsdl->fetchWSDL($url); //get the wsdl
	$wsdlCache->put($wsdl); //create cache file
}
$client = new nusoap_client($wsdl, TRUE);
//set your login for the soap client
$client->setCredentials($username,$apikey);
/* end Nusoap WSDL cache setup */

// Check for an error
$err = $client->getError();
if ($err) {
    // Display the error
    echo 'Constructor error' . $err . "\n";
    exit; // At this point, you know the call that follows will fail
    
}

//make an API call
$result = $client->call('ping', Array(), 'natsapiadmin_wsdl');
var_dump($result);

Example with URL fall back

In the above example, there is only an attempt to connect with a nusoap WSDL cache file, or a newly created nusoap wsdl object. It is possible for existing cache files to have errors, and for newly created wsdl objects to cause errors when used to connect. As such, you may want to add additional checking to try rebuilding the cache or load from the wsdl URL directly if needed. The example below includes checks for these two scenarios, but please keep in mind you may encounter other scenarios in your usage that require modifying/expanding this example. Please be sure to test this before adding it live to important API calls and add any code needed for your specific usage.

<?php

/* Exmple API call using nusoap_wsdlcache class */
/* nusoap includes */
require_once('nusoap/lib/nusoap.php');
if(!class_exists("nusoap_wsdlcache")){ 
	require_once('nusoap/lib/class.wsdlcache.php');
}

//API login vars
$username = '<admin_username>'; // your admin username
$apikey = '<api_key>'; // your api key
$url = 'http://<your_nats_domain>/admin_api.php?wsdl'; // change <your_nats_domain>  to be domain of your NATS install

/* Nusoap WSDL cache setup */
//cache vars
$cache_created_now = FALSE;
$url_connect = FALSE;
$cache_dir = "<cache_dir>"; // change <cache_dir> to be the directory for storing cache files
$wsdl_cache_lifetime = <wsdl_cache_lifetime>; // change  <wsdl_cache_lifetime> to an amount in seconds

//construct cache object
$wsdlCache = new nusoap_wsdlcache($cache_dir, $wsdl_cache_lifetime);
//try to get cached wsdl file for this URL
$wsdl = $wsdlCache->get($url);
if (empty($wsdl)) {
	$cache_created_now = TRUE;
	$wsdl = new wsdl();
	$wsdl->setCredentials($username,$apikey);
	$wsdl->fetchWSDL($url);
}

//first try loading from WSDL object/cache file
$client = new nusoap_client($wsdl, TRUE);
$err = $client->getError();

if(!empty($err)){
	if (!empty($cache_created_now)) {
		//loading new WSDL object failed.  Fall back on the URL
		$url_connect = TRUE;
	}
	else{
		//cached wsdl file failed, let's try to clear/rebuild cache
		$wsdlCache->remove($url); 
		$wsdl = new wsdl();
		$wsdl->setCredentials($username,$apikey);
		$wsdl->fetchWSDL($url);
		$client = new nusoap_client($wsdl, TRUE);
		$retryErr = $client->getError();
		if(!empty($retryErr)){
			//still getting an error from new WSDL object, fall back the url directly
			$url_connect = TRUE;
		}
		else{
			//no error, store the new cache
			$wsdlCache->put($wsdl);
		}
	}
}
else{
	if (!empty($cache_created_now)) {
		//we loaded from new WSDL object with no error, store the WSDL in cache
		$wsdlCache->put($wsdl);
	}
}	

//fall back on wsdl URL if needed
if(!empty($url_connect)){
	// Cache/wsdl object failed, let's try to connect with direct URL instead. 
	$client = new nusoap_client($url, TRUE);
	//Check for an error
	$err = $client->getError();
	if ($err) {
		// We tried WSDL cache + direct WSDL URL and still can't connect.  Display the error
		echo 'Constructor error: ' . $err . "\n";
		exit; // At this point, you know the call that follows will fail
		
	}
}

//set the login credentials for the nusoap $client
$client->setCredentials($username,$apikey);

//make an API call
$result = $client->call('ping', Array(), 'natsapiadmin_wsdl');
var_dump($result);

Manually clearing the cache

If you have stored the cache files for your NATS API calls in it's own directory, you can manually clear the cache by going into your <cache_dir> and removing the wsdlcache-XXX, and wsdlcache-XXX.lock file created for the NATS API wsdl. If you have other cache files stored with the ones created by NATS API calls, you may instead want to use a script to delete the cache for the particular URL.

<?php
	
$url = 'http://<your_nats_domain>/admin_api.php?wsdl'; // change <your_nats_domain>  to be domain of your NATS install

/* Nusoap WSDL cache setup */
$cache_dir = "<cache_dir>"; // change <cache_dir> to be the directory for storing cache files
$wsdl_cache_lifetime = <wsdl_cache_lifetime>; // change  <wsdl_cache_lifetime> to an amount in seconds

/* clear cache */
$wsdlCache->remove($url); 
?>

Checking the cache improvement

The first time you make an API call using the nusoap wsdlcache, there will still be a request for the wsdl file to start the cache. Once the cache file is created, subsequent API calls will load the wsdl from the cache file rather than trying to request it. You can tail your apache access logs on your NATS server while making API calls to see the cache improvement. When making the call the first time, you will see a "GET" entry to "admin_api.php?wsdl", and a "POST" entry to "POST /admin_api.php". With a valid cache file available, you should only see a "POST" entry to "/admin_api.php".