Using BlueDot's SOAP API with PHP

In the last few weeks I've been working on a Flex based browser for BlueDot. It's been a good project for bringing together a few of my current interests (Flex, MVC, SOAP, PHP, BlueDot). The project is developing nicely but it's not ready for show and tell. But one thing I didn't find when I started the project was information about accessing the API with php. Don't take that the wrong way the BlueDot SOAP API is well documented. But I just couldn't find any information that directly related to using the API with PHP. Hence I thought it might save fellow travellers some leg work if I posted an example.

To get this working I'm using PHP4 and NuSOAP and naturally you'll need a BlueDot account with some Dots and Tags . You'll need to download NuSOAP into folder that will be accessible from your script. If you will be doing a lot of work with SOAP you'll want to place it somewhere that can be easily accessed by all of your projects. I thought we could start by getting the datetime of your last dot. This is the simplest method in BlueDot's API and consequently there are less points to go wrong. So let's look at some code:

<?php
require_once("nusoap/lib/nusoap.php");

//set path to server and create new client
$serverpath = "https://secure.bluedot.us/BlueDotApi.asmx?WSDL";
$client = new soapclient($serverpath);
?>

Just the basics to get started. The first line adds the nusoap libraries which obviously need to be available before they can be called. Next we create a variable with the path to the BlueDot API. Then we create the soap client. The soap client will format the SOAP request based on the details we provide and manage the request.

$client->setCredentials('your_username','your_password','basic');
$err = $client->getError();

if ($err)
{
print_r($err);
}

BlueDot uses basic authentication to check that you have a right to the data we are requesting. Consequently you'll need to use setCredentials with your BlueDot username and password. The third parameter just tells the soap client that we'll be using basic authentication. Finally we use getError to check that the login was passed. In our example we are checking for an error and printing it out so we can debug the login. If there isn't an error then we can proceed to calling the method.

$client->setCredentials('your_username','your_password','basic');
$err = $client->getError();

if ($err)
{
print_r($err);
}
else
{
$namespace ='http://bluedot.us/api';
$soapAction = "http://bluedot.us/api/GetLastUpdatedDateTime";

$result = $client->call('GetLastUpdatedDateTime',"",$namespace,$soapAction);
}

To get the datetime of the last update we call 'GetLastUpdatedDateTime'. This method requires no parameters and returns a datetime (i.e 2007-04-24T23:23:54). The namespace will be the same for all the calls you'll use. But the soap action will change depending on the method name. Next you'll want to check that the call was processed without any problems.

if ($client->fault)
{
print_r($client->response);
}
else
{
$err = $client->getError();

if($err)
{
print_r($err);
}
else
{
echo "<pre>";
print_r($result);
echo "</pre>";
}
}

We can use fault to check for faults and then use response to print out the fault details. If there is no fault we can test for an error and print the error if one exists. If there are no problems then lets just print out the result. Depending on where and how you are going to use the result you'll need to do something more useful here. So lets see it altogether:

<?php

require_once("../../serverScripts/nusoap/lib/nusoap.php");
//set path to server and create new client
$serverpath = "https://secure.bluedot.us/BlueDotApi.asmx?WSDL";
$client = new soapclient($serverpath);
$client->setCredentials('your_username','your_password','basic');
$err = $client->getError();

if ($err)
{
print_r($err);
}
else
{
$namespace ='http://bluedot.us/api';
$soapAction = "http://bluedot.us/api/GetLastUpdatedDateTime";
$result = $client->call('GetLastUpdatedDateTime',"",$namespace,$soapAction);

if ($client->fault)
{
print_r($client->response);
}
else
{
$err = $client->getError();

if ($err)
{
print_r($err);
}
else
{
echo "<pre>";
print_r($result);
echo "</pre>";
}
}
}
?>

Hopefully that's enough to get you started. Most of the available methods are as simple to call. The exceptions are RenameTag (requires two strings) and Search (which requires a Search object; you may want to leave this till you've had a bit of practice). The main differnce between GetLastUpdatedDateTime and most methods is that it returns a very simple object. For example, getTags returns an array of Tags that contain the tags name and a count of the number of dots it's used for. But the differnce is how you process the result not how you make the SOAP call.