Share via


June 16, 2015

We are pleased to announce the following enhancements to version 1.16 of the AppNexus ImpBus API.

Warning

In addition to new features, this release includes breaking changes. We will therefore support two versions of the API for the next 60 days, as stated in our Breaking Changes policy.

Version 1.15: This version does not include breaking changes. The https://api.adnxs.com endpoint will continue to point to version 1.15 for 60 days. After that time, this endpoint will point to version 1.16.

Version 1.16: This version does include breaking changes and new features. For the next 60 days, to use this version, you must point directly to it in your calls, for example, https://api.adnxs.com/v1.16.

Breaking changes

All of the changes described in this section are only present in version 1.16.

One supported SSL endpoint

As of the 1.16 release, the only supported endpoint for ImpBus API users will be the (SSL-enabled) https://api.adnxs.com. Non-secure HTTP endpoints will no longer be supported. Other URLs will no longer be supported.

Stricter JSON type checking

Version 1.16 will continue to automatically convert (cast) "integerish" strings to integers. For example, "123" will still be converted to 123.

However, beginning with version 1.16, the API will no longer warn when automatically converting a "non-integer" string such as "foo" to 0 when such a string is passed into a field expecting an integer. Instead, it will throw an error and the call will fail.

Changed error messages

The following error messages are changing:

  • Anywhere the message "Error occured while processing your request" appears, it's being changed to fix the misspelling in "occurred". The new message will be "Error occurred while processing your request".
  • If a database transaction fails, the error message is currently "SYSTEM::updating". These messages have been changed to provide more detail, depending on the type of error. The new messages are:
    • SYSTEM::DEADLOCK_MAX_ATTEMPTS::A database error occurred. Please try your request again.
    • SYSTEM::DB_UNKNOWN::A database error occurred. Please try your request again.

Changed services

Creative service

The following changes are being made to the Creative Service:

  • The thirdparty_page_id field is now inside the thirdparty_page object in both the request and the response.
  • A template is now required for every creative. Creatives configured using the previously-deprecated format and media_subtype elements will no longer function. A non-null id is now required in the templateobject for any PUT or POST.

Bidder profile service

The following changes are being made to the Legacy Bidder Profile Service.

Removed fields

The inventory_source_targets field is being removed:

Targeting region, country, and city will be by ID

We are changing region, country, and city-based targeting to target by ID. The following fields are being updated.

Country targets

The country_targets field will be passed in using IDs as follows:

"country_targets": [
    {
        "id": 1 // id of US
    },
    {
        "id": 2 // id of AS
    }
]

Furthermore, the contents of this field in response to a GET call will become:

"country_targets": [
        {
          "id": 1,
          "name": "United States",
          "code": "US"
        }
      ]

To see a list of all of the countries available for targeting, make a GET request to https://api.adnxs.com/country/meta.

Region targets

The region_targets field will be passed in using IDs as follows:

"region_targets": [
    {
        "id": 1 // ID of NJ region in US
    },
    {
        "id": 2 // ID of NY region in US
    }
]

Furthermore, the contents of this field in response to a GET call will become:

"region_targets": [
       {
          "id": 1,
          "name": "New York",
          "code": "NY",
          "country_name": "United States",
          "country_code": "US"
        }
      ]

For a list of the supported regions, you can check the Region Service meta by making a GET request to https://api.adnxs.com/region/meta.

City targets

The city_targets field will change slightly to the following ("region_id", an integer, is being replaced by "region_code", a string):

"city_targets": [
       {
          "id": 123,
          "name": "Queens",
          "region_name": "New York",
          "region_code": "NY",
          "country_name": "United States",
          "country_code": "US"
        }
      ]

To search the City Service for cities that you are interested in targeting, call the service using a name (or part of a name) as shown below. This example will find cities with the string "New" in their names.

curl -bc https://api.``adnxs``.com/city?like_city=New

Third-party page access service

Changed field type

In the Third-Party Page Access Service, the type of the thirdparty_page_id field is changing from string to integer. This is necessary because Facebook only accepts numeric values in this field.

Reporting service

New method for retrieving reports

The method for retrieving a report from the Report Service is changing. Beginning with the 1.16 release, the workflow will change to be the same as used by the Console API. Specifically, the steps will be:

  1. Create a report by POSTing JSON to the Report Service. This returns a report ID.
  2. Check the status of your report by making a GET request to the service using the report ID you received in Step 1.
  3. When the "execution_status" of the request from Step 2 is "ready", the URL for downloading the report will be in the "url" field.
  4. Finally, you'll make a GET call to the Report Download Service using the contents of the "url" field to retrieve the report data.

Report download service

The report-download service now returns more consistent and accurate headers in its responses. For these responses, no JSON is returned. The possible return values are:

  • 200: OK.
  • 202: Report request accepted and still pending for processing.
  • 404: The report ID was not provided.
  • 405: Unsupported method was requested (POST, PUT, DELETE).
  • 410: Purged; report has been deleted.
  • 500: Internal Error. The reporting API returned a malformed response, could not report data, or any other uncaught exceptions.
Removed service

The June 16, 2015 is being removed.

Bidding protocol changes

We are updating our Bid Request to remove the following fields:

  • inventory_class
  • inventory_source_id

Non-breaking changes

The changes in this section apply to version 1.15 of the API.

New services

Deal from package service

New service

The Deal From Package Service allows buyers to create a deal from an existing package.