AdButler API: Building a Basic Tool

Read Time: 12 minutes

We’re coming up on four months since we released AdButler’s beta API, and I thought it was high-time I wrote something to help people get acquainted with it. Today we’re going to create a tool that allows you to delete a publisher and all the banner zones within it.

Creating our delete tool will get you some experience with the API and how the PHP client works. By the end of this guide, you should have a basic understanding of the various endpoints and how the client is structured. I’m not teaching you everything (we have documentation for that), but I am trying to give you a solid foundation. If you get stuck at any point feel free to comment below.

To follow this guide, you’ll need a few things:

  • A basic knowledge of PHP (the language we’ll be working in)
  • An active AdButler subscription
  • The API key for your account
  • A server to run your code on (can be a local server, like MAMP)

The tool we’re building is going to run entirely off of PHP. It won’t have any sort of interface, but you could easily add one once we’ve built out the basics. As with any coding project, it’s good to plan out what we’re trying to do before we start. Our tool will:

  1. Register an API key
  2. Retrieve the objects we’re looking to delete
  3. And delete all of the objects

Let’s get started.

Our first step will be getting the PHP client. You can download it from here, or install it using Composer in your terminal:

Either way, you’ll want to create a new PHP document and import the AdButler client based on your directory structure. You’ll use the below code at the top of the document if you manually downloaded the client:

Or, if you’re using composer, you can use the autoload feature:

We now have full access to the AdButler client. The client contains methods for all the API actions, which saves you from having to write messy cURL requests. Before doing anything with the library, we have to initialize it with our API key.

Without the API key none of the commands will work. Also be aware of what API key you’re working with. If you’re using the test key, you’ll only be able to edit objects created with the test key. On the other hand, if you’re using your live API key you could accidentally delete something. Once something is deleted, it’s gone forever.

For the purposes of this guide, I recommend using your live API key. That way, we can see the changes we’re making by loading up AdButler.

The AdButler API is broken down into a bunch of classes related to the familiar objects in your dashboard. There’s one for banners, campaigns, advertisers, etc. There are also classes for things that are a bit more abstract, such as schedules (the settings you create on the assignment page) and placements (the relationship between, say, a zone and a campaign).

See our the complete AdButler API Documentation

View API Documentation

Almost all the classes inherit from the same basic object, though, and have common methods among them. Let’s start by looking at the “retrieve” method.

The retrieve method takes the ID of something in AdButler and returns it. Before we’re able to go any further, we’ll need a publisher. Let’s head to the AdButler dashboard right now and create a test publisher and some banner zones that will, very shortly, be deleted. Use whatever settings you want when making these. Once you’re done, look in the URL of the publisher page to find the ID. The ID I’m working with today is 37607. Let’s try retrieving the publisher with the PHP client. First save the script below:

And then navigate to it in a web browser. You should see a response displayed which lines up with the publisher you just made. Go ahead and change the name of the publisher in your dashboard. When you retrieve the publisher again, the object will be updated.

The retrieve method is one of the base methods that all the objects in the library has. By changing the type of object we’re retrieving (and using a proper ID), you can modify the code to retrieve information about an advertiser, a banner, a placement, or anything, really.

You can also store the retrieved object in a local variable in order to access its methods and properties. For instance, if we wanted to change the name of the advertiser using the API, we could retrieve it, edit the “name” property, and then call its “save” method. Let’s do that.

If you go into your AdButler dashboard, you should find the publisher is now named “Wow it worked”.

Now that we’ve gone over the basics of how the PHP client works, we can start to build our deleting tool. Let’s start with a basic function that retrieves a publisher by ID and deletes it using the “delete” method.

You can try running this function if you want, but you’ll need create another test publisher to keep following the guide. Let’s hold off running our script for now and move onto the next step: deleting a publisher’s zones.

You might be wondering why we need to delete zones separately from deleting a publisher. In the AdButler UI, you don’t have to. Once a publisher is deleted you also lose all the zones associated with it. But the same thing doesn’t happen in the API.

With the release of our API AdButler can now have “orphan objects”. Orphan objects are objects that exist on your account without any parents. A zone exists as a complete object, regardless of publisher. A banner also exists the same way. That means that when we delete a publisher, we’re leaving behind a bunch of orphaned zones. So we need to delete those separately. We’ll do that by first finding getting those zones.

The PHP client has a method called “retrieveAll”. It returns an object containing some information, as well as a collection of all instances of that thing. By default the method only retrieves ten, so if you have more than ten zones on your account you’ll need to pass in a different limit.

To retrieve all of the zones on an account versus one zone, the code is really similar to retrieving one.

If you run this function you’ll see all the zones on your account. And because we don’t have to worry about IDs, we can easily create a function that takes the name of the class we’re looking for and returns all of it.

We now have a function that we can use to retrieve all the banner zones on an account. We could also easily make this delete all instances by looping through the returned object and calling the delete method on each element. That would probably be a disaster.

Instead, we need to make sure the function only deletes certain zones. We need to look at the returned zones and find out which ones are related to the publisher we’re deleting. The key to this is in the banner zone object. Specifically, the “publisher” property.

The publisher property contains the ID of the publisher for the zone. By comparing the publisher property to an ID we pass in, we’re able to tell which zones we should be deleting. We can then call the delete method and log a confirmation:

And if we now combine this code with our retrieveAndDeletePublisher function, we get a pretty handy tool for testing purposes:

Our tool takes a publisher ID, retrieves the publisher, retrieves all zones on the account, and deletes the ones associated with it. When first learning our API, you’re probably going to be making a lot of zones (and publishers and banners and campaigns), so keep this tool around for easy cleanup.

You may have noticed that I’ve thrown a little bit of logging into the function to help with bigger accounts. Logging is very important when working with larger functions, so make sure you include it in your API development.

If you’re looking for some other tasks to help you learn the API and PHP client, try extending out our tool. A couple things you could try (in order of difficulty):

  • Deleting all zones, not just banner zones, within a publisher
  • Deleting everything on an account.
  • Deleting all banners within a publisher (hint: publisher->zone->placement->banner)

As always, feel free to comment below if you get stuck or if you’ve built something else with our code.

Liam Workman

Liam is an account manager and blog king at SparkLit, the SaaS company behind AdButler and FourEyes. He loves rock climbing, hiking, coding, and being your friend.