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
.
All of the changes described in this section are only present in version 1.16.
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.
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.
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.
The following changes are being made to the Creative Service:
- The
thirdparty_page_id
field is now inside thethirdparty_page
object in both the request and the response. - A template is now required for every creative. Creatives configured using the previously-deprecated
format
andmedia_subtype
elements will no longer function. A non-nullid
is now required in thetemplate
object for anyPUT
orPOST
.
The following changes are being made to the Legacy Bidder Profile Service.
The inventory_source_targets
field is being removed:
We are changing region, country, and city-based targeting to target by ID. The following fields are being updated.
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
.
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
.
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
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.
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:
- Create a report by
POST
ing JSON to the Report Service. This returns a report ID. - Check the status of your report by making a
GET
request to the service using the report ID you received in Step 1. - When the
"execution_status"
of the request from Step 2 is"ready"
, the URL for downloading the report will be in the"url"
field. - 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.
The June 16, 2015 is being removed.
We are updating our Bid Request to remove the following fields:
inventory_class
inventory_source_id
The changes in this section apply to version 1.15 of the API.
The Deal From Package Service allows buyers to create a deal from an existing package.