Version 5.0
AdvertServe User Manual :: v5.0

API Reference

Introduction

What is the API?

The API allows you to programmatically manipulate and retrieve data from the ad server using command line tools or a programming language such as Java or PHP.

There are many possible use cases for the API, but some of the more common ones would be:

In fact, if you were so inclined you could actually develop your own control panel entirely from scratch, which might be of interest to a large ad network for example.

What are the requirements?

To use the API, you simply make HTTP GET or POST requests to the API modules and the API will send back a JSON or XML response. This simplicity was a design goal because it allows you to use the API with virtually any programming language because almost all programming languages include HTTP and JSON/XML support. In fact, you can even use it from your browser address bar or with a command line HTTP client such as curl or wget.

How can I use the API?

First, you need to enable the API. To do that, log in to the control panel as a privileged administrator and click on the Settings icon in the toolbar. Then click on Basic > API in the navigation menu on the left. Change the API Usage option to Enabled and then press the Save Changes button.

Make sure to take note of the Secret Key as you will need to include it with every private API request!

It should go without saying that this API key should remain a secret. You should never expose your API key in client-side code. It is also strongly recommended to use HTTPS so that data transmission is encrypted. For an added level of security you can also configure an IP-based firewall in the API settings to limit access.

Now that you have the API enabled, let's assume for example that you want to create about 100 different themes for your ad network to use with your publishers. Creating them one by one with the control panel would take a lot of time! You already have the list of theme names in a text file named themes.txt with the names of the themes one per line like the following:


Example One
Example Two
Example Three
...

Using a few simple Linux commands, you can read the themes.txt and create the themes by making an HTTP POST request to /servlet/control/api/themes/create (which is the URL of the API module to create themes) with the secret and name parameters:


SECRET_KEY=a78bf24c5a23581aceba1c5f51ac4cad
cat themes.txt | while read name
do curl -d "secret=$SECRET_KEY&name=$name" http://example.com/servlet/control/api/themes/create
done

Alternatively the equivalent code written in Perl and using the LWP::UserAgent module would be:


#!/usr/bin/perl -w

use strict;
use LWP::UserAgent;

my $API_KEY = "a78bf24c5a23581aceba1c5f51ac4cad";
my $API_URL = "http://example.com/servlet/control/api/themes/create";

my $ua = LWP::UserAgent->new;

open (TXT, "<themes.txt") || die "Error opening themes.txt file: $!\n";

while (<TXT>) {
  my $name = $_;

  chomp($name);

  my %params = (
    "secret" => "$API_KEY",
    "name" => "$name"
  );

  my $response = $ua->post($API_URL, \%params);

  if ($response->is_success) {
    print $response->decoded_content;
  }

  else {
    die $response->status_line;
  }
}

close(TXT);

After each of the themes is created, using either the Linux commands or the Perl code, the API will respond with XML (by default) containing the ID# of the created theme:


<id>123</id>

If you prefer to have the API output JSON simply add an output=json parameter to the HTTP request and you'll get the following JSON response instead:


{ "id" : 123 }

If you are using a programming language to work with the API, you could capture that ID# and store in another database or file so that you could later query the themes by their ID# if for example you wanted to synchronize the themes with another system.

What happens if something goes wrong when creating the themes though? Good question! The API will return a 500 status response (internal server error) with an error message like the following:

XML


<error>
The <i>Name</i> field must contain a unique value.
</error>

JSON


{ "error" : "The <i>Name</i> field must contain a unique value." }

So, you can see that you tried to create a theme with the same name as one that already exists, which is of course not allowed.

API Modules

Click on any of the links below for instructions on how to use the available API modules. In the instructions you will find the URL(s) for each of the modules. You'll also find information about required and optional parameters, data validation rules, and example JSON and XML responses.

Public API Modules

These public API modules are designed to be called from client-side code and do not require using an API key.

Private API Modules (API Key Required)

These private API modules are designed to be called from server-side code and require using an API key. We recommend storing your API key in an environment variable on the system(s) that need API access. This is safer than embedding your API key in your server-side code as anyone with access to your code would know your API key. By storing it in an environment variable only the administrator(s) of the system(s) would have access to it. It is also strongly recommended to use HTTPS so that data transmission is encrypted. For an added level of security you can also configure an IP-based firewall in the API settings to limit access.