Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 31 Next »

AppNexus API Introduction

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.

curl -b cookies -c cookies -X POST -d @some.json 'http://apiurl/creative'

The above command is making a POST request to the creative service.

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

Indicated that you are going to upload a file, in this case "some.json"

'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.

Examples of using PHP, Ruby, Python, or JAVA with our APIs are coming soon.

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. For example:

Max GET Request Output

Users can paginate results from GET responses by specifying by specifying start_element and num_elements in query string. I.e. http://api.appnexus.com/creative*?start_element=0&num_elements=50* will return the first 50 elements found in the GET request. In order to retrieve the next 50, simply set start_element=50.

The maximum number of elements that can be returned regardless of your request is 100.

  • The first element is element 0.
  • All GET responses will have a "count" property showing the total number of elements matching that GET request.
  • This will also apply to non-reporting services, such as the creative search service, that are requested with methods other than GETs.

Examples

Input and Output Throttling

On a related note, we allow a max of 60 writes and 100 reads per member per minute. If you require more reads or writes per minute, please reach out to your account manager.

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]

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.

  • No labels