The AdGear API offers developers the ability to programmatically interact with the AdGear platform.

We recommend that you familiarize themselves with the AdGear admin web interface before delving into API work, as the paradigms are the same and the API mimics the web interface closely in terms of functionality, flow, and even URLs.

Access

Every user with access to the AdGear Admin web interface may, free of charge, enable API access on their own account. You can do this by:

1. Logging into AdGear
2. Access your account settings by clicking on your username on the top-right corner
3. Enabling the checkbox "Enable HTTP Digest API?"
4. Save, and note down the auto-generated API password

Once the above is completed, your account is API-enabled and you may immediately start using the API.

Protocol

The API is based on the HTTP protocol and, as much as possible, mirrors the URLs you see when browsing the admin interface.

Base URL

The base URL of the API can be obtained by prepending "api." to the hostname of the web interface you're browsing. For example, if you're browsing http://admin.adgear.com/, the base API URL would be http://api.admin.adgear.com/

Authentication

Every API call is required to be authenticated using the HTTP DIGEST mechanism. The username is your own username you login to admin with, and the password is the auto-generated one you obtained from the initial setup above.

Input format

When supplying data to the API, your HTTP request must be in one of the following formats, which you must indicate using the Content-Type HTTP header:

• application/x-www-form-urlencoded or multipart/form-data: Standard browser-like FORM encoding
• application/json: JSON document
• text/xml: XML document

The inner structure of the input document is defined by the API endpoint you're interacting with, and is the same independent of the input format (the format encapsulates the needed structure). Check the endpoint's documentation.

When using browser-like FORM encoding, which does not offer data type richness to indicate required nesting structure, the Rails "bracket-notation" in the key names must be used. See specific examples of the specific API endpoint you're interacting with.

Output format

Independent of the input format you've supplied, you must request an output format via the "extension" at the end of the URL. Supported output formats are:

• json
• xml

The inner structure of the output document is defined by the API endpoint you're interacting with, and is the same independent of the output format (the format encapsulates the needed structure). Check the endpoint's documentation.

Endpoints

All API endpoints, including the base URL, return a "_urls" structure with a list of further relevant API endpoints to follow. When interacting with the API, you should only hardcode the API base URL, and follow the appropriate returned URLs from there to what you need.

File uploads

When manipulating entities which require you upload an actual file, you must first upload the file itself to the uploads end point using standard FORM multipart upload. This must be done independent of the incoming/outgoing formats you're consuming for the rest of the API calls.

Once the upload is successful, the uploads end point will return information about the upload in the format of your choosing. The critical attribute is the "id" of the upload, which you may then use in a future call to reference the file you've just uploaded.

Files uploaded to the uploads end point and not referenced within 30 minutes will be deleted.

HTTP all the way down

The following HTTP properties are utilized by the API:

• HTTP VERB (GET/POST/PUT/DELETE) to indicate desired action on endpoint
• HTTP response codes to indicate success or failure