NBT SOAP Interface Guide


Table of Contents

  1. Scope:
  2. Overview:
  3. NuSOAP:
  4. Implementation:
  5. Public Methods:
  6. Private Methods:
  7. NBT Clients:

Scope:

Starting with NBT Hardcore, NBT now has a SOAP interface for retrieving and updating information from the central NBT database(s).  This document outlines the availible methods and their uses which will allow web developers to write 3rd party applications to that can interface with the NBT league automation.

Overview:

The SOAP protocol was chosen to because of it's extensibility and the availibility of existing well used classes defined in PHP. The SOAP protocol is defined as

SOAP is a lightweight protocol for exchange of information in a decentralized, distributed environment. It is an XML based protocol that consists of three parts: an envelope that defines a framework for describing what is in a message and how to process it, a set of encoding rules for expressing instances of application-defined datatypes, and a convention for representing remote procedure calls and responses. SOAP can potentially be used in combination with a variety of other protocols; however, the only bindings defined in this document describe how to use SOAP in combination with HTTP and HTTP Extension Framework.

Th SOAP protocol is used as a means to transfer information between applications existing on remote web servers and the central NBT automation and datatbases. 

NuSOAP:

NBT uses the NuSOAP libarary to speed the development of SOAP services. NuSOAP web pages tells us:
NuSOAP is a rewrite of SOAPx4, provided by NuSphere and Dietrich Ayala. It is a set of PHP classes - no PHP extensions required - that allow developers to create and consume web services based on SOAP 1.1, i WSDL 1.1 and HTTP 1.0/1.1.

These classes take care of the low level SOAP operations allowing developers to concentrate on the aplication instead of the SOAP interface. NuSOAP also handles the automatic creation of WSDL pages. Interfacing with NuSOAP is as easy as passing arrays to and from PHP functions and classes.  If you know how to manipulate arrays in php then you will wil have no problems using NuSOAP.

Implementation:

All  SOAP methods are provided by services.php. This file is the heart of the system. It defines the methods avaible for use, the format of the data passed between them and the actual php fiunctions that get the work done.  There are two types of methods, public and private. The private methods requre the establishment of a session by passing login information to the SOAP server via the auth method.  All NBT SOAP methods are named based and do not use database ids. This causes extra work for the SOAP developer but it aviods revealing database information unnecessarily. For example instead of using the database ID for a row in the player_data table you would use the players callsign. A list of available SOAP methods can be obtained from services.php.

Public Methods:

Public SOAP methods are directly accessible with out any authentication. A very simple method would be getUnitListing. This method can be easily scripted on the client side by implementing the code below. After the code is executed the variable $unitListing will contain a comma seperated list of unit names.

include 'lib/nusoap.php';
$c = new soapclient('http://www.netbattletech.com/nbt-hc/services.php');
$unitListing = $c->call('getUnitListing');

A more advanced example of a public SOAP method would be  getUnitData which sends a request for a specifiec unit's data. The call statement changes a little by passing an array with a single element of unitname. 

include 'lib/nusoap.php';
$c = new soapclient('http://www.netbattletech.com/nbt-hc/services.php');
$unitData = $c->call('getUnitData', array('unitname' => $name);

Once executed $unitData will contain an array consisting of the information for the requested unitname.

    Array ( [ID] => 507 
	    [UnitName] => Avanti's Angels 
            [Unit_Abbrv] =>
	    [Active] => 0 
	    [ActiveTime] => 0 
            [Viewable] => 0 
            [Class] => Merc 
            [CO_Callsign] => Wilhelm Barret 
            [CO_Email] => many_tails@hotmail.com 
            [XO_Callsign] => Vanguard 
            [Homepage] => http://www.clansnowraven.com 
            [House] => 0 
	    [Description] => Survivors without equal, Marcus GioAvanti's Angels have 
			        faced vicious Clan assaults. They have matched wits with 
			        House Kurita. Brushed back brutal reprisals from the 
			        Marian Hegemony and the Word of Blake. The Angels 
                                take all comers. 
            [Logo] => 0 
            [Timezone] => Eastern
            [Pilots] => 5 
            [Battles] => 0 
            [Wins] => 0 
            [Losses] => 0
            [Win_Percent] => 0.00 
            [Planets_Gained] => 0 
            [Planets_Lost] => 0 
            [Net_Planets_Gained] => 0 
            [Offensive_PA_Battles] => 0
            [Defensive_PA_Battles] => 0 
            [Offensive_GRaid_Battles] => 0
            [Defensive_GRaid_Battles] => 0 
            [Offensive_Raid_Battles] => 0
            [Defensive_Raid_Battles] => 0 
            [Offensive_Industry_Battles] => 0
            [Defensive_Industry_Battles] => 0 
            [Offensive_Factory_Battles] => 0 
            [Defensive_Factory_Battles] => 0 
            [Offensive_Recon_Battles] => 0
            [Defensive_Recon_Battles] => 0 
            [Offensive_Tresspass_Dispute_Battles] => 0 
            [Defensive_Tresspass_Dispute_Battles] => 0
            [Total_Tresspass_Dispute_Battles] => 0 
            [Total_PA_Battles] => 0
            [Total_GRaid_Battles] => 0 
            [Total_Raid_Battles] => 0
            [Total_Industry_Battles] => 0 
            [Total_Factory_Battles] => 0
            [Total_Recon_Battles] => 0 
            [Tags] => =A²=
)

An even more complex method is the auth method. The auth methods is technically a public method but it plays an important role in creating a SOAP session by authenticating a SOAP request and returning a session id. All private methods requires the session id be passed along with the SOAP request.  The auth method is implemented on the client side as:

include 'lib/nusoap.php';
$authRequest ['unitname'] =  'Outworlds Alliance';
$authRequest['password'] = 'asdf123';
$authRequest['callsign'] = 'BassPlayer';
$soapObject = array();
$authData = array();
$battleData = array();
$soapObject = new soapclient('http://localhost/nbt-hc/services.php');
$authData = $soapObject->call('auth', array('AuthRequest' => $authRequest));

AuthRequest is defined as a complex type, a type of nested xml definition. When services.php receives the auth SOAP request it automagically converts AuthRequest to a array and passes it to the auth function.  The auth function will then return an array containing a the callsign, session_id and status. The status will be either 0 for successfull of 1 for login failure. 

Private Methods:

Private SOAP methods are methods that require that a valid session is created prior to calling and the session id of the session is passed when called . All private methods will first verify the session is a valid before continuing onto process the SOAP request. Below is client code to authtenticate to the NBT HC database, update a players Aissignment value and then destry the SOAP session.

include 'lib/nusoap.php';
$authRequest['unitname'] =  'Outworlds Alliance';
$authRequest['password'] = 'asdf123';
$authRequest['callsign'] = 'BassPlayer';
$soapObject = array();
$authData = array();
$battleData = array();
$soapObject = new soapclient('http://localhost/nbt-hc/services.php');
$authData = $soapObject->call('auth', array('AuthRequest' => $authRequest));
if($authData['status'] == 0) {
    $playerData['sess_id'] = $authData['sess_id'];
    $playerData['Callsign'] = 'BassPlayer';
    $playerData['Assignment'] = 'New Assignement;
    $status = $soapObject->call('updatePlayerData', array('PlayerData' => $playerData));
    $deauthRequest['sess_id'] = $authData['sess_id'];
    $deauthData = $c->call('deauth', array('deauthRequest' => $deauthRequest));
}

NBT Clients:

NBT Clients are a collection of SOAP clients that you can run locally on your site that will communicate via SOAP to the NBT HC server. Right now only the bio and Solaris character pages are implemented. Other clients will follow like awards and hopefully battles. It's mostly for people who want to show off their HC bio or Solaris character on their own site but don't want to install the full roster. A new dynamic graphic signature will show your solaris stats proudly in your forums or webpages.

Obtaining

You can get NBT-Clients from http://www.angmar.com.

Installation

http://www.yourdomain.com/nbt-clients/bio.php?callsign=yourcallsign
or
http://www.yourdomain.com/nbt-clients/bio.php?callsign=yourcallsign
or
< img src="http://www.yourdomain.com/nbt-clients/yourcallsign.png>
or
[img]http://www.yourdomain.com/nbt-clients/yourcallsign.png[/img]

 

Proud sponsors of the NetBattleTech League System
Return to NBT-HC HomePage