AppNexus Api Wrapper

Usage no npm install needed!

<script type="module">
  import anxApi from '';


AppNexus Api Wrapper

npm version Build Status Build Dependencies Coverage Status


npm install anx-api --save

Usage Example

var AnxApi = require('anx-api');

// Create a new instance with api target
var anxApi = new AnxApi({
    target: ''
    token: 'SESSION_TOKEN', // (optional) see also anxApi.login(...)
    rateLimiting: true

anxApi.get(<serviceName>).then(function (res) {
}).catch(function (err) {



var anxApi = new AnxApi(config);



  • target - (string) required base api url
  • token - (string) optional session token
  • request - (object) optional request object
  • timeout - (integer) optional request timeout in milliseconds (default: 60000) Triggers ConnectionAbortedError error.
  • userAgent - (string) optional user agent
  • rateLimiting - (boolean) optional rate limiting
  • concurrencyLimit - (integer) optional max concurrent requests
  • beforeRequest - (function) optional before request opts filter (see beforeRequest)
  • afterRequest - (function) optional after request response filter (see afterRequest)
  • environment - (enum:node|browser) optional. node - force axios to run as if in node and not the browser (usefull for testing with jest/jasmine).

Instance Methods


Issues a GET request

anxApi.get('service url')
anxApi.get('service url', opts)


Response Object

  • statusCode - (number) Http response code
  • headers - (object) Response headers
  • body - (object) Response payload
  • req - (object) Request options
  • requestTime - (number) Actual on network request time in milliseconds
  • totalTime - (number) Total request time including concurrency and rate limiting delays in milliseconds


  • id - (number OR array(number))
  • service uri - (string)
  • opts - (object) see Request Options


Usage and parameters are the same as #get accept it pages through api calls. Response body is parsed as json.


Issues a POST request with a payload'service url', <payload>)'service url', <payload>, opts)


  • service uri - (string)
  • payload - (string|object)
  • opts - (object) see Request Options


Issues a PUT request with a payload

anxApi.put('service url', <payload>)
anxApi.put('service url', <payload>, opts)


  • service uri - (string)
  • payload - (string|object)
  • opts - (object) see Request Options


Issues a DELETE request

anxApi.delete('service url')
anxApi.delete('service url', opts)



Authenticates with the API and returns a token. The token will be reused for future requests.

anxApi.login('username', 'password').then(function (token) {

    // The api object is now logged in. Optionally store the token.




Request Options

The get, post, put, and delete methods can be called with an opts object. The opts object has the following request options.

  • uri - (string) service uri
  • body - (object) required payload for .post and .put
  • headers - (object) optional request header overrides
  • startElement - (string) optional start index
  • numElements - (integer) optional number of records to return
  • params - (object) optional query string parameters
  • mimeType - (string) optional mimetype
  • timeout - (integer) optional request timeout in milliseconds (defaults to config timeout)
  • encodeParams - (boolean) optional whether or not params object should be encoded. (default: false)


// Fetch the third page of 25 creatives
    uri: 'creative',
    startElement: 50,
    numElements: 25

anxApi.get('creative', {
    params: {
        start_element: 50,
        num_elements: 25


Transforming Request Options and Responses


Request options can be modified prior to request execution by supplying a beforeRequest transform function in the constructor. The function should either return a new options object or null which will be ignored.

var anxApi = new AnxApi({
    beforeRequest: function (opts) {
        var modifiedOpts = _.assign({}, opts, {
            // make changes to options
        return modifiedOpts;


Request responses can be modified prior to being delivered by supplying a afterRequest transform function in the constructor. The function should return either a new response object or null which will be ignored.

var anxApi = new AnxApi({
    afterRequest: function (res) {
        var modifiedRes = _.assign({}, res, {
            // make changes to response
        return modifiedRes;

Error Handling

anxApi.get('creative').then(function (res) {
}).catch(function (err) {
    if (err instanceof NotAuthenticatedError) {
        console.log('Your not logged in!');

Error Object Types

  • Error - generic error type
  • NetworkError
    • DNSLookupError - target host could not be looked up [ENOTFOUND]
    • ConnectionAbortedError - request timeout was reached [ECONNABORTED]
    • ConnectionRefusedError - [ECONNREFUSED]
    • ConnectionResetError - [ECONNRESET]
    • ConnectionTimeoutError - [ETIMEDOUT]
    • SocketTimeoutError - [ESOCKETTIMEDOUT]
  • ApiError - base api error type
    • NotAuthenticatedError - token is invalid or expired
    • NotAuthorizedError - Unauthorized to make request
    • RateLimitExceededError
    • SystemServiceUnavailableError
    • SystemUnknownError
    • TargetError - target was not supplied

Error Object Properties

  • id - Api error id
  • code - Api error code
  • message - Brief error description
  • req - Request options used in failed request
  • res - Raw failed response

Custom Request and Debugging

The following are two different methods of modifying and or spying on requests made to the api.

Wrap the internal request function

anxApi._config.request = _.wrap(anxApi._config.request, function (request, opts) {
    console.log('DEBUG: ', opts);
    return, opts);

Pass in a custom request object

var request = require('request');

function customRequest(opts) {
    return new Promise(function (resolve, reject) {

        // Customize the request

        request(opts, function (err, res) {
            if (err) {

                // Add additional error handling

            } else {

                // Customize the response


var anxApi = new AnxApi({
    target: process.env.ANX_TARGET,
    token: 'SESSION_TOKEN',
    request: customRequest


Running unit tests

Run the unit test suite from the project root, make sure you've run npm install first:

npm test


See LICENSE file