This section will present the most common operations, and describe how to perform them with the API.

List Publisher Campaigns

Accomplished via:

1. Issuing a GET to http://api.admin.adgear.com/.xml to retrieve the "directory"
2. Looping over the URLs, looking for the URL with the name "list_publisher_campaigns". Example:

   1. <_url>
            <method>GET</method>
            <input_element nil="true" xsi:nil="true"></input_element>
            <output_element>collection_publisher_campaigns</output_element>
            <name>list_publisher_campaigns</name>
            <url>http://api.admin.adgear.com/publisher_campaigns.xml</url>
          </_url>

3. Issue a second call to the found URL, using the specified HTTP verb (GET http://api.admin.adgear.com/publisher_campaigns.xml).  Output:

   1. <?xml version="1.0" encoding="UTF-8"?>
      <collection_publisher_campaigns xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://adgear.com/api/schemas/xml#output">
        <publisher_campaigns type="array">
          <publisher_campaign>
            <placements_count type="integer">2</placements_count>
            <ctr type="float">0.0</ctr>
            <percent_goal_achieved type="decimal">13.03</percent_goal_achieved>
            <revenue type="decimal">0.0</revenue>
            <created_at type="datetime">2009-03-06T19:43:58-05:00</created_at>
            <updated_at type="datetime">2010-04-15T19:15:08-04:00</updated_at>
            <ad_units_count type="integer">1</ad_units_count>
            <objective_impressions type="integer">0</objective_impressions>
            <advertiser_id type="integer">16</advertiser_id>
            <objective_clicks type="integer">0</objective_clicks>
            <end_at type="datetime">2012-01-19T23:59:59-05:00</end_at>
            <name>In-House</name>
            <delivered_impressions type="integer">53</delivered_impressions>
            <id type="integer">31</id>
            <start_at type="datetime">2010-01-10T00:00:00-05:00</start_at>
            <_urls type="array">
              <_url>
                <method>GET</method>
                <input_element nil="true" xsi:nil="true"></input_element>
                <output_element>collection_ad_units</output_element>
                <name>list_ad_units</name>
                <url>http://api.admin.adgear.com/publisher_campaigns/31-in-house/ad_units.xml</url>
              </_url>
              <_url>
                <method>PUT</method>
                <input_element>publisher_campaign</input_element>
                <output_element>publisher_campaign</output_element>
                <name>update</name>
                <url>http://api.admin.adgear.com/publisher_campaigns/31-in-house.xml</url>
              </_url>
              <_url>
                <method>GET</method>
                <input_element nil="true" xsi:nil="true"></input_element>
                <output_element>collection_publisher_placements</output_element>
                <name>list_publisher_placements</name>
                <url>http://api.admin.adgear.com/publisher_campaigns/31-in-house/publisher_placements.xml</url>
              </_url>
              <_url>
                <method>PUT</method>
                <input_element nil="true" xsi:nil="true"></input_element>
                <output_element>publisher_campaign</output_element>
                <name>unarchive</name>
                <url>http://api.admin.adgear.com/publisher_campaigns/31-in-house/unarchive.xml</url>
              </_url>
              <_url>
                <method>POST</method>
                <input_element>publisher_placement</input_element>
                <output_element>publisher_placement</output_element>
                <name>create_publisher_placement</name>
                <url>http://api.admin.adgear.com/publisher_campaigns/31-in-house/publisher_placements.xml</url>
              </_url>
              <_url>
                <method>POST</method>
                <input_element>ad_unit</input_element>
                <output_element>ad_unit</output_element>
                <name>create_ad_unit</name>
                <url>http://api.admin.adgear.com/publisher_campaigns/31-in-house/ad_units.xml</url>
              </_url>
              <_url>
                <method>GET</method>
                <input_element nil="true" xsi:nil="true"></input_element>
                <output_element>publisher_campaign</output_element>
                <name>read</name>
                <url>http://api.admin.adgear.com/publisher_campaigns/31-in-house.xml</url>
              </_url>
              <_url>
                <method>PUT</method>
                <input_element nil="true" xsi:nil="true"></input_element>
                <output_element>publisher_campaign</output_element>
                <name>archive</name>
                <url>http://api.admin.adgear.com/publisher_campaigns/31-in-house/archive.xml</url>
              </_url>
            </_urls>
            <delivered_clicks type="integer">0</delivered_clicks>
          </publisher_campaign>
        </publisher_campaigns>
        <_urls type="array">
          <_url>
            <method>POST</method>
            <input_element>publisher_campaign</input_element>
            <output_element>publisher_campaign</output_element>
            <name>create</name>
            <url>http://api.admin.adgear.com/publisher_campaigns.xml</url>
          </_url>
          <_url>
            <method>GET</method>
            <input_element nil="true" xsi:nil="true"></input_element>
            <output_element>collection_publisher_campaigns</output_element>
            <name>list</name>
            <url>http://api.admin.adgear.com/publisher_campaigns.xml</url>
          </_url>
        </_urls>
      </collection_publisher_campaigns>
      

Creating a new Ad Unit

Accomplished via:

1. Querying the directory, following the list of campaigns as shown above, choosing which campaign the created ad unit will be under
2. For the chosen campaign, loop over its own "_urls" entity looking for the URL named "create_ad_unit". Example:

   1.         <_url>
                <method>POST</method>
                <input_element>ad_unit</input_element>
                <output_element>ad_unit</output_element>
                <name>create_ad_unit</name>
                <url>http://api.admin.adgear.com/publisher_campaigns/31-in-house/ad_units.xml</url>
              </_url>
      

3. From the directory, downloading the list of ad unit templates (the URL with the name "list_ad_unit_templates") - each template will contain information required to instantiate an ad unit based on that template
4. From the directory, downloading the list of formats (the URL with the name "list_formats")
5. Putting it all together:  Issue an HTTP POST to the create_ad_unit end point, where the root XML element is "ad_unit", and its attributes populated appropriately, including the template name as well as the format_id.

Updating a publisher placement

Accomplished via:

1. Querying the directory, following the list of campaigns as shown above
2. For the appropriate campaign, obtain the list of placements by following the list_publisher_placements URL
3. For the appropriate placement, follow the URL with the "update" name:
   1. The input root element will be "publisher_placement"
   2. All fields, as indicated by the XSD, are optional.  Only supply fields that you wish to modify.  Fields that you do not supply will not be modified.
   3. On success, the response will be the "publisher_placement" root entity from the output namespace.  On failure the response will be the "errors" entity.