OpenX API – Introduction (Part 1)

We use OpenX frequently at BlackRiver as the most open and customizable ad serving platform both for many of our clients and our own internal projects. Unfortunately, with the introduction of the commercial OpenX-based services, like the hosted packages, paid consulting and the OpenX ad network, the amount of documentation for the community edition of OpenX (open-source) seems to be on the decrease. Especially when it comes to OpenX API – there is almost nothing out there but a few blog posts and outdated code samples. We would really like to share our experiences (both positive and negative) with OpenX API as we strongly believe that the OpenX platform should remain easy accessible and open to the public.

As you might already know, the OpenX API service allows us to gain remote control of the pretty much the entire functionality of the ad serving platform. OpenX provides us with two versions (v1 and v2) of the API. You can still find some minimal documentation on v1 version of the API, but it has been deprecated since OpenX 2.7, thus we are going to focus on v2. The API service is based on the RPC (criticized by many as being inferior to REST) protocol, so as an obvious solution, we decided to use the latest PHP XML_RPC2 library provided by PEAR (http://pear.php.net/package/XML_RPC2/). The installation is fairly straight forward, if you have PEAR already installed, simply run pear install XML_RPC2

Now with the XML_RPC2 library setup, let us look into a specific code example:

require_once 'XML/RPC2/Client.php';
$oxLogin = array("username"=>"admin","password"=>"admin_password");
$opts = array('prefix' => 'ox.');
$advertiserId = 3;
 
$client = XML_RPC2_Client::create('http://domain.com/openx/www/api/v2/xmlrpc/', $opts);
 
try {
 
    $sessionId = $client->logon($oxLogin['username'],$oxLogin['password']);
 
    $result = $client->getAdvertiser($sessionId,$advertiserId);
    print_r($result);
 
    $result = $client->advertiserDailyStatistics($sessionId,$advertiserId);
    print_r($result);
 
    $client->logoff($sessionId);
 
} catch (XML_RPC2_FaultException $e) {
 
    // The XMLRPC server returns a XMLRPC error
    die('Exception #' . $e->getFaultCode() . ' : ' . $e->getFaultString());
 
} catch (Exception $e) {
 
    // Other errors (HTTP or networking problems...)
    die('Exception : ' . $e->getMessage());
 
}

Even though the above code is fairly self-explanatory, there are a few things to take into consideration. The login credentials MUST be of the main account used on the OpenX installation, creating a separate administrator account just for the API service is not going to work. The “ox.” prefix for the RPC service is default and does not need to be changed. In this example, we authenticate (login) with the API, and then use the sessionId to retrieve a specific advertiser’s information as well as the daily stats for that specific advertiser. The advertiserDailyStatistics function returns an array of all days in which the advertiser was active, if there is no specific date passed as one of the parameters.

In the next little while, we are going to post more articles on specific OpenX API functions (perhaps even a full list with explanations – which was never provided by OpenX core team) and how to control OpenX Advertisers, Publishers, Campaigns, Zones and Banners as well as custom OpenX delivery limitations plugins and integration with open-source platforms like WordPress.