AppNexus API Introduction
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.
REST Semantics
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:
POST |
create/add |
GET |
read/retrieve |
PUT |
update/modify |
DELETE |
delete |
Using cURL
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.
curl -b cookies -c cookies -X POST -d @some.jsonfile 'http://apiurl/creative'
Chunk of Request |
What it Means |
---|---|
-c cookies |
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. |
-b cookies |
Retrieves the authentication token that you previously stored in this file. |
-X |
Indicates that you are going to make a certain type of request, in this case "POST." |
-d |
Indicates that you are going to upload a file, in this case "some.jsonfile." |
'http://apiurl/creative' |
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. |
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.
object
array
string
assignment of an alphanumeric value to a string
assignment of a numeric value to a string
Example:
JSON Field Values
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.
Type |
Description |
Example |
---|---|---|
Boolean |
True/False |
True |
String(100) |
String of 100 characters or less |
male_26_likes_cheese |
Int |
Integer |
87 |
Unsigned |
Positive integers only |
745 |
Float |
Floating point number |
3.00 |
Double |
Floating point number with twice the bit space of a float. |
3.00 |
Enum |
One of a number of preassigned values |
male/female |
Timestamp |
Date and time string in the form YYYY-MM-DD HH:MM:SS |
2009-01-14 05:41:04 |
Array |
More than one value allowed |
[87,45] |
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"
Authentication
Before you can use the APIs, you will authenticate yourself with your username and password. Please see Authentication for details.
Response Codes
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 bidder, member, tag, or creative. (In the example below we are using cookies to store our authentication token and adding the file "tag" to the Tiny Tag Service.)
Error Messages
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.
Error_ID |
Meaning |
Logic |
---|---|---|
NOAUTH |
Authentication information is either missing or invalid |
Use /auth to get a valid token |
UNAUTH |
The user is not authorized to take the requested action |
Check 'error' message and make sure logic is correct in code |
SYNTAX |
The syntax of the request is incorrect |
Use the 'error' message to identify the issue and fix the code |
SYSTEM |
A system error has occurred |
Contact AppNexus |
INTEGRITY |
A client request is inconsistent; for example, an attempt to delete a default creative attached to an active placement |
Check the request for integrity |
SSL
Please use https://api.appnexus.com for secure data and authentication.