AppNexus API Semantics
This page explains the basics of our API structure. If you are brand new to APIs, please see APIs for Beginners. Please also see API Usage Constraints and then you may wish to walk through a typical setup.
The URL for the Production API is https://api.appnexus.com. Changes made with this API affect the production AppNexus Console. Only authorized users should alter information or settings in this environment.
The URL for the AppNexus Client-Testing API is http://api-console.client-testing.adnxs.net. New features are tested in this environment, prior to release in the production environment. We prefer that new API users play around in the client-testing environment to get familiar with our tools before making changes in production. There are several Client-Testing UI environments, and changes in api-console.client-testing.adnxs.net will affect all of them.
AppNexus API services are "RESTful." REST (Representational State Transfer) is a type of software architecture in which requests model the communication from a web browser to a web server. Below are the central REST methods used in the AppNexus API Services and their uses:
When making a POST or PUT request, you pass along a JSON-formatted file with the data to create or update. For PUT requests, only the fields included in the JSON-formatted file will be updated, except in the case of arrays. When updating an array, all fields in the array are completely replaced with the information in the JSON-formatted file. This means that, if the array already includes fields, you must include those fields in the JSON-formatted file; otherwise, they will be deleted from the array.
Example PUT request for updating an array
This example walks you through the process of properly updating the pixels array of creative 503577.
First, let's look at the creative. Note that the pixels array already includes one pixel.
Next, we create the JSON-formatted file for adding a new pixel to the creative. In the file, we include both the new pixel that we want to add and the pixel already included in the creative.
If we don't include the existing pixel in the JSON-formatted file, our update will delete that pixel from the creative.
Then we make a PUT call to update the creative with the information in the JSON-formatted file. Note that, in the response, the pixels array includes both the new and old pixels.
In our documentation we use curl to make REST requests. Curl is a command-line tool for transferring files with URL syntax, supporting FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, LDAP, LDAPS and FILE. The example scripts on each API wiki page should make clear the structure of the curl commands you will need to run AppNexus API services, but here's a generic example making a POST request. The example is hitting the creative service, probably to add a new creative to our system.
Chunk of Request
What it Means
Creates a text file called "cookies" and stores your session token (assigned by the Authentication Service). Please note, this is not necessary to include after the initial authentication, but we tend to include it in examples just to keep things neat.
Retrieves the authentication token that you previously stored in this file.
Indicates that you are going to make a certain type of request, in this case "POST."
Indicates that you are going to upload a file, in this case "some.jsonfile."
The URL of the service you are making the request to. Best to use quotes in case you have any funky characters in your URL.
Use Single Quotes Around Your Request URL
Some requests require single quotes around your request URL, as in the above curl request. If you get an error message, make sure your request URL has single quotes before troubleshooting further.
Filtering and Sorting
Please see: API Filtering and Sorting
Meta: What Fields Are Available
In almost all services you can add
/meta to the end of the URL and get a list of the fields included in the service. You will also see the "type," such as integer, and whether or not you can sort and filter by that field. For example:
JSON Basic Structure
A Basic JSON structure
Here's the syntax of the components of a JSON object and what they mean.
assignment of an alphanumeric value to a string
assignment of a numeric value to a string
JSON Field Types
POST and PUT requests require JSON-formatted data. For PUT requests, only the JSON fields included in a request will be updated. All other fields will be unchanged.
Different fields require different types of values. The table of types below extends those defined in the JSON standard. For more information about JSON, see http://json.org.
True or false.
A string of 100 characters or less.
A generic decimal number.
A floating-point number with 32-bit precision.
A floating-point number with 64-bit precision.
One of a number of predetermined values.
A floating-point numeric value used to represent money. For more information, see Vertica's Numeric Data Types.
A date and time string in the form YYYY-MM-DD HH:MM:SS.
See 'Timestamp' above.
A wrapper for any sub-fields under the current field. In the example that follows, the field
A list containing one or more values.
A Note on Underscores and Hyphens
Most multi-word fields and values use underscores rather than hyphens, but we are cleaning up some occasional inconsistencies. Please note, however, that service names are hyphenated.
Service example: https://api.appnexus.com/insertion-order
Field example: "audit_type_direct": "platform_or_self"
Before you can use the APIs, you will authenticate yourself with your username and password. Please see Authentication Service for details.
All API Services return JSON-formatted data. When Service calls are successful, the JSON response will include a "status" field set to "OK". The response to POST and PUT calls will also include the ID of the relevant object, such as member, tag, or creative, as well as any relevant attributes of that object. Every response will include "dbg_info" fields that convey information about the API call and response, such as the API machine that processed the request and the version of the API.
In the example below, we are using cookies to store our authentication token and adding the file "creative" to advertiser 123 with the Creative Service.
The API machine which processed the request.
Whether or not the API machine ran SQL queries on a database slave.
The database the query was executed on.
The number of reads made.
The limit on the number of reads.
The time period over which the read_limit is enforced.
The number of writes made.
The limit on the number of writes.
The time period over which the write_limit is enforced.
The amount of time it took to process the API request, expressed in milliseconds.
The Unix timestamp of the start time of processing, including milliseconds (right side of the decimal point).
The version of the API.
When invalid input is sent to the API - for example, an incorrect password - a JSON response will be returned with "error" and "error_id" fields.
The "error" field is useful for debugging purposes, as it contains a verbose description of the error. The "error_id" field can be used programatically as follows.
Authentication information is either missing or invalid
Use /auth to get a valid token
The user is not authorized to take the requested action
Check 'error' message and make sure logic is correct in code
The syntax of the request is incorrect
Use the 'error' message to identify the issue and fix the code
A system error has occurred
A client request is inconsistent; for example, an attempt to delete a default creative attached to an active placement
Check the request for integrity
Please use https://api.appnexus.com for secure data and authentication.