End points - AdGear Support

Unlike a classical RPC API, a REST API does not have a fixed set of end points.

Once your account is set up for API access as per the Introduction, you will be able to:

Use this document to understand the general structure and patterns of the AdGear API end points
Query the API, retrieving both entity data, as well as further API metadata useful for further queries
Check the technical documentation for the input and output fields expected for each end point

Formats

Throughout the examples in this documentation we will be requesting output in the XML format, however you may choose JSON instead. The structure of both formats is exactly the same, both in terms of input and output fields.

The API's XML format has the following characteristics:

Extensive schemas (XSD) for the input and output entities, used both as the basis of the API documentation as well as entity validation
Wide adoption and client library availability
No notion of data types without the aid of a third-party definition

The API's JSON format has the following characteristics:

Lack of a standardized schema/documentation mechanism. When inputting and outputting JSON, please refer to the entity's XML documentation. The structure of the entities is exactly the same.
Less widely used compared to XML
Full set of native data types

Your preference for the input and output formats will be dictated by the language you're consuming your API with, and your level of comfort dealing with the XML and/or JSON facilities of said language. Your need for strict element validation may require XML, while a need for more dynamic data types and a more native mapping between your objects and the API's objects may lead you towards JSON.

Testing

You may find the UNIX "curl" command very helpful in interacting with the AdGear API before writing any code. An example of its usage is as follows:

curl -s --digest --user quentin:204e75c27e83f1424dd2aab30df99c0f37346c064650b88a451a16b5ab8e879d http://api.admin.adgear.com/.xml

To test an end point that requires POSTed data, you need to save the data in a file first (for example: input.xml), as well as indicate the content type of the input with the Content-Type HTTP header:

1.curl -s --digest -d @input.xml -H "Content-Type: application/xml" --user quentin:204e75c27e83f1424dd2aab30df99c0f37346c064650b88a451a16b5ab8e879d http://api.admin.adgear.com/.xml

First Call

The first call to make, both when testing as well as from your code, is to retrieve the directory. This is done via an HTTP GET call to the base url directly, and it outputs something like so:

001.<?xml version="1.0" encoding="UTF-8"?>
002.<directory xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://adgear.com/api/schemas/xml#output">
003.  <_urls type="array">
004.    <_url>
005.      <method>GET</method>
006.      <input_element nil="true" xsi:nil="true"></input_element>
007.      <output_element>collection_zones</output_element>
008.      <name>list_zones</name>
009.      <url>http://api.admin.adgear.com/zones.xml</url>
010.    </_url>
011.    <_url>
012.      <method>GET</method>
013.      <input_element nil="true" xsi:nil="true"></input_element>
014.      <output_element>collection_advertisers</output_element>
015.      <name>list_advertisers</name>
016.      <url>http://api.admin.adgear.com/advertisers.xml</url>
017.    </_url>
018.    <_url>
019.      <method>POST</method>
020.      <input_element>publisher_campaign</input_element>
021.      <output_element>publisher_campaign</output_element>
022.      <name>create_publisher_campaign</name>
023.      <url>http://api.admin.adgear.com/publisher_campaigns.xml</url>
024.    </_url>
025.    <_url>
026.      <method>POST</method>
027.      <input_element>zone</input_element>
028.      <output_element>zone</output_element>
029.      <name>create_zone</name>
030.      <url>http://api.admin.adgear.com/zones.xml</url>
031.    </_url>
032.    <_url>
033.      <method>GET</method>
034.      <input_element nil="true" xsi:nil="true"></input_element>
035.      <output_element>collection_data_profiles</output_element>
036.      <name>list_data_profiles</name>
037.      <url>http://api.admin.adgear.com/data_profiles.xml</url>
038.    </_url>
039.    <_url>
040.      <method>GET</method>
041.      <input_element nil="true" xsi:nil="true"></input_element>
042.      <output_element>collection_formats</output_element>
043.      <name>list_formats</name>
044.      <url>http://api.admin.adgear.com/formats.xml</url>
045.    </_url>
046.    <_url>
047.      <method>POST</method>
048.      <input_element>data_profile</input_element>
049.      <output_element>data_profile</output_element>
050.      <name>create_data_profile</name>
051.      <url>http://api.admin.adgear.com/data_profiles.xml</url>
052.    </_url>
053.    <_url>
054.      <method>GET</method>
055.      <input_element nil="true" xsi:nil="true"></input_element>
056.      <output_element>collection_users</output_element>
057.      <name>list_users</name>
058.      <url>http://api.admin.adgear.com/publishers/14-mina/users.xml</url>
059.    </_url>
060.    <_url>
061.      <method>GET</method>
062.      <input_element nil="true" xsi:nil="true"></input_element>
063.      <output_element>reports_directory</output_element>
064.      <name>list_reports</name>
065.      <url>http://api.admin.adgear.com/reports.xml</url>
066.    </_url>
067.    <_url>
068.      <method>GET</method>
069.      <input_element nil="true" xsi:nil="true"></input_element>
070.      <output_element>collection_sites</output_element>
071.      <name>list_sites</name>
072.      <url>http://api.admin.adgear.com/sites.xml</url>
073.    </_url>
074.    <_url>
075.      <method>POST</method>
076.      <input_element>user</input_element>
077.      <output_element>user</output_element>
078.      <name>create_user</name>
079.      <url>http://api.admin.adgear.com/publishers/14-mina/users.xml</url>
080.    </_url>
081.    <_url>
082.      <method>POST</method>
083.      <input_element nil="true" xsi:nil="true"></input_element>
084.      <output_element>upload</output_element>
085.      <name>create_upload</name>
086.      <url>http://api.admin.adgear.com/uploads.xml</url>
087.    </_url>
088.    <_url>
089.      <method>POST</method>
090.      <input_element>advertiser</input_element>
091.      <output_element>advertiser</output_element>
092.      <name>create_advertiser</name>
093.      <url>http://api.admin.adgear.com/advertisers.xml</url>
094.    </_url>
095.    <_url>
096.      <method>POST</method>
097.      <input_element>site</input_element>
098.      <output_element>site</output_element>
099.      <name>create_site</name>
100.      <url>http://api.admin.adgear.com/sites.xml</url>
101.    </_url>
102.    <_url>
103.      <method>GET</method>
104.      <input_element nil="true" xsi:nil="true"></input_element>
105.      <output_element>collection_publisher_campaigns</output_element>
106.      <name>list_publishe
107.r_campaigns</name>
108.      <url>http://api.admin.adgear.com/publisher_campaigns.xml</url>
109.    </_url>
110.  </_urls>
111.</directory>

Inspecting the directory, you can see it's essentially a list of URLs that your API can follow at will. Each URL has a unique name that your code can look for when looping, as well as:

The URL to contact if you wish to reach this end point
The HTTP method required when contacting the URL
The root element expected to be supplied by you when contacting the end point
The root element expected to be returned by AdGear upon a successful response

Depending on the user accessing the API, the facilities available to them will be different than the ones shown above. It is important that you do not hard-code any URLs related to the AdGear API except the initial base URL.

Once you follow one of the URLs in the directory to invoke an end point, the returned element will, almost always, contain a child "_urls" element. This will contain a further set of URLs that you may consume further, and so on.

The finder

The AdGear API offers a finder end point (found in the directory under name "find_entity"). You may use this service if you know AdGear's internal type and AdGear's internal ID of an entity, and wish to jump directly to it without making a series of API calls going through its parents first.

To use the finder, call the finder end point supplying the query parameters "entity_type" and "entity_id". Example:

1.curl -s --digest --user quentin:204e75c27e83f1424dd2aab30df99c0f37346c064650b88a451a16b5ab8e879d "http://api.admin.adgear.com/find.xml?entity_type=PublisherCampaign&entity_id=31"

The output is another "directory" entity, containing the single "read" end point of the entity it found. Example:

01.<?xml version="1.0" encoding="UTF-8"?>
02.<directory xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://adgear.com/api/schemas/xml#output">
03.  <_urls type="array">
04.    <_url>
05.      <method>GET</method>
06.      <input_element nil="true" xsi:nil="true"></input_element>
07.      <output_element>publisher_campaign</output_element>
08.      <name>read</name>
09.      <url>http://api.admin.adgear.com/publisher_campaigns/31-in-house.xml</url>
10.    </_url>
11.  </_urls>
12.</directory>

Errors

If AdGear encounters an error with your request, the following will happen:

The HTTP code will be in the error range of codes (4xx, 5xx)
The root element returned will be the "errors" element, no matter what the expected (successful) root element was for the end point