Burningbird

One of the programming jobs I’ve had recently was to provide PHP functions to access the Newsgator SOAP API; hiding as much of the SOAP bits as possible. I used the nuSOAP PHP library as the basis for my work. Though SOAP functionality is built into PHP 5, my client, like most people, are still using PHP 4, and nuSOAP has a very clean implementation.

For those who might want to give the API a shot, I’ll walk through some sample code that should be easily modified as interested. I had hoped to write a more complete application, but have ran out of time.

The Newsgator API requires an account in order to test the code, but you can sign up for one at no charge. When you get an account, you’re given an online Newsgator Location in which to add subscriptions. You’re also given the ability to create new locations, as well as folders, and to subscribe to and read, syndication feeds. The API itself is split into five main categories for the five SOAP endpoints: Locations, Folders, Subscriptions, Feeds, and Posts.

Each SOAP engpoint page lists the web service methods for the specific item, including a description of the parameters and values returned. An important element when looking at the page is to find a link to the endpoint at the bottom. Clicking on it opens a window asking for the account username and password. Once you enter these, the endpoint page opens, containing links for each of the methods.

Clicking on a method link opens up another page, usually containing a form, and an example SOAP request and response. These latter are essential in order to determine the values used with nuSOAP. You can also test the web service by typing values into the form and invoking the method. If, that is, the parameters are simple values rather than programmatic structures, such as arrays.

Once you’ve looked through the API methods to see what parameters are needed, and explored the actual SOAP request and response, it’s just a matter of plugging in values within the nuSOAP functions. To demonstrate, I’m going to walk through a program that creates a SOAP client, queries the service for all subscriptions for a given location, and then accesses and prints out links to the individual items for the subscriptions.

In the program, I first create a SOAP client using the appropriate endpoint, checking for any error afterwards. (Complete source code is provided later, so no worries about any gaps in the code):

// create SOAP client
$client = new soapclient(”http://services.newsgator.com/ngws/svc/Subscription.asmx”);
$err = $client->getError();
if ($err) {
err($client,$err);
die();
}

I’m not using a proxy or WSDL, so no other parameters other than the endpoint are set.

Next, I define the method’s parameters, in this case a location string and a synchronization token. This latter value is used to synchronize the data between method calls, and in the results you’ll see this returned as part of the response. Using this provided synch value in the next method call ensures that the data, such as the count of unread items for each subscription, is fresh.

// set parameters
$params = array(
‘location’ => $location,
’syncToken’ => $synctoken
);

During the initial web service request, the synch token is blank.

Once the method parameters are set, I added code to authenticate the user:

// authenticate against the service
$client->setCredentials($user, $pass,’basic’);

Note that this uses example uses BASIC authentication; Newsgator also supports DIGEST authentication.

The Newsgator API token is passed in a SOAP header, which I build manually next. Note that the token must be authenticated with the service, so you’ll need to specify the appropriate service namespace:

// create SOAP header for Newsgator API
$hdr = “<ng:NGAPIToken xmlns:ng=’http://services.newsgator.com/svc/Subscription.asmx’>
<ng:Token>$token</ng:Token></ng:NGAPIToken>”;

Finally, we can now invoke the service:

// invoke SOAP service
$result = $client->call(’GetSubscriptionList’, $params,’http://services.newsgator.com/svc/Subscription.asmx’,
‘http://services.newsgator.com/svc/Subscription.asmx/GetSubscriptionList’,
$hdr,false, ‘rpc’,’literal’);

// check for error
if ($client->fault) {
echo ‘<h2>Fault</h2><pre>’; print_r($result); echo ‘</pre>’;
} else {
$err = $client->getError();
if ($err) {
echo ‘<h2>Error</h2><pre>’ . $err . ‘</pre>’;
}
}

In this function call, the SOAP method is the first parameter, followed by the parameters, the SOAP endpoint (namespace), the SOAP action, the manually created header, the serialization style (’rpc’), and the serialization for the parameters (’literal).

The nuSOAP function processes any XML returned as multi-dimensioned arrays. With this service call, the subscriptions are returned as OPML, values of which you can access by walking through the array:

// decipher the array, based on OPML
$opml = $result[”opml”];
$body = $opml[”body”];
$outline = $body[”outline”];
$syntoken = $opml[”!ng:token”];
foreach ($outline as $key => $sub) {
$feed = $sub[”!ng:id”];
$title = $sub[”!title”];
$url = $sub[”!htmlUrl”];
echo “<a href=’$url’>$title</a><br />”;
}

After each subscription is accessed, the feed identifier ($feed) is then used to invoke another service to get the news for the feed. The complete application demonstrates this.