NATS4 API nusoap wsdlcache

From TMMwiki
Jump to: navigation, search
NATS 4
SOAP API
API
API Best Practices
WSDL Cache
Add Affiliate
Add Member Note
Admin Get Adtools
Adtool Categories
Adtool Types
Affiliate Get Campaigns
Bulk Import Adtools
Caching
Decode Natscode
Expire Manual Member
Get Affiliate Campaigns
Get Affiliate Hit Data
Get Affiliate Loginids
Get Affiliate Nats Codes
Get Affiliate Payout
Get Affiliate Program Campaign List
Get_Affiliate_Program_Campaign_List
Get Member Details
Get Member Instant Upgrade String
Get Member Package Upgrade String
Get Member Token Rebuy String
Get Member Upsell String
Get Payment Data
Get Payvia Rule
Get Profit Loss Report
Ping
Record Member Login
Search Affiliate Info
Search Member Info
Send Email API Function
Set Affiliate Admin Settings
Set Affiliate Customs
Set Affiliate Defaults
Set Affiliate Information
Set Affiliate Settings
Set Member Details
Set Payment Status
Set Payvia Rule
REST API
API Overview
API Best Practices
REST API PATH UPDATES
Adtools
GET /adtools/admin
GET /adtools/categories
GET /adtools/types
POST /adtools/importdump
Affiliate
GET /affiliate/campaigns
GET /affiliate/hitdata
GET /affiliate/payout
GET /affiliate/searchinfo
POST /affiliate/addaffiliate
POST /affiliate/invoice
PATCH /affiliate/setadminsettings
PATCH /affiliate/setcustoms
PATCH /affiliate/setdefaults
PATCH /affiliate/setinformation
PATCH /affiliate/setpayviainfo
PATCH /affiliate/setsettings
PATCH /affiliate/status
Member
GET /member/upsellstring
GET /member/tokenrebuystring
GET /member/instantupgradestring
GET /member/packageupgradestring
GET /member/signupplusstring
GET /member/cancelstring
GET /member/details
GET /member/searchinfo
GET /suggestedcanceloffers
PATCH /member/setdetails
PATCH /member/setexpiration
POST /member/addnote
POST /member/recordlogin
PUT /member/expiremanual
Option
GET /option/getrule
PATCH /option/editrule
POST /option/addrule
PUT /option/edittext
Payments
GET /payments/getpayments
GET /payviarule
PATCH /payments/setstatus
PATCH /payviarule
Report
GET /profitlossreport
Service
GET /service/decodenatscode
GET /service/ping
POST /service/sendemail

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)
//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);

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.

/* continued from above */
//try to get cache from file
$wsdl = $wsdlCache->get($url);
if (empty($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 (empty($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
/* nusoap includes */
require_once('nusoap/lib/nusoap.php');
if(!class_exists("nusoap_wsdlcache")){ 
	require_once('nusoap/lib/class.wsdlcache.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
/* construct cache object */
$wsdlCache = new nusoap_wsdlcache($cache_dir, $wsdl_cache_lifetime);
/* 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".