Best Practices for Building on Xandr APIs
We're thrilled that you're taking advantage of our platform by grabbing raw data, hooking in your own pieces of the ad serving puzzle, or otherwise building on top of our infrastructure. There are a few ground rules that will make sure you have the best experience possible, and keep your applications healthy as our API evolves. Please stay in touch with your implementation consultant as you get started building.
Filter your results
Filtering allows you to specify a subset of objects to be returned. For example, the following call would return only active creatives:
For fields of the type int, double, date, or money, you can append
max_ to the filter. For example, the following request would return only campaigns that have been modified on or after January 1, 2013:.
For each service, you can find out which fields are filterable and sortable by appending
/meta to the service URL. For more information, see API Semantics.
Paginate your results
Even though you might only have 5 creatives in the system now, you should still write your application in a way that it takes advantage of the pagination support since this number is likely to increase in the future. You can paginate results by specifying
num_elements in the query string of the GET request. For example, the following request would return the first 50 objects in the response:
To retrieve the next 50, you would simply set
The maximum number of objects that can be returned, regardless of pagination, is 100. Please note that if you request over 100 objects, we will only return the first 100 and will not provide an error message. For more information, refer to the API Semantics page.
Throttle your calls
There are limits to the number of requests you can make against our APIs per minute. We categorize these limits into read and write requests. Currently, the default read and write limit is 1000 per minute. You can monitor the response header for current rate limits for your requests. These counters will reset at the end of the minute, but if you exceed them, you will get an error response. Rate limit information is present in the following fields of the response header:
When write limits are exceeded, you will receive a "429 Too Many Requests" error response. Retry the request in the number of seconds specified in the
Retry-After field in the header.
Below is an example of the header values in response to a request that exceeded a member's rate limit.
Pass field values rather than relying on defaults
It's best practice to pass the field values that you want rather than relying on defaults. If default values change, and you are relying on defaults, you may experience unexpected results.
Avoid unnecessary updates
When updating objects, do not pass fields that are not changing. A good way to avoid this is to cache your GET calls, compare the cache to the changes you want to make, and then make PUT calls only for what's different.
Avoid unnecessary authentication
You can authenticate successfully 10 times within a 5-minute period. Any subsequent authentication attempts within those 5 minutes will result in an error.
When you authenticate, you receive an authorization token that remains active for 2 hours. It is best practice to re-authenticate only after you receive the "NOAUTH" error_id in your call responses. If you follow this practice, the restraint above should have no impact on your implementation.
For authentication instructions, see Authentication Service
Use a config-driven API end-point
Make sure that you can change the API base URL easily. In the example below, the API URL is defined as a variable and can be used throughout the code base. If that URL should ever need to change, it can be modified in a single location.
Build an API wrapper
Centralizing the code where you send requests and handle responses is a great practice. This will allow you to do logging, error handling and more in one location.
Do not pull all reports at the same time
This can cause the reporting backend to be overloaded, resulting in delayed reports, and can even impact reports that are run later in the day.
Read the entire API Wiki before using the API
There are many tips, tricks and examples throughout the API Wiki that will be useful in developing your integration.
Use integration codes
Rather than store Xandr IDs, you can use the integration codes to refer to object in the API. These codes must be unique across an object type and Xandr member. The example below uses an integration code to identify a campaign.
Do not assume an API call was successful
All successful API calls will receive a response containing a "status" of "OK". If the response does not contain this status, the call failed for some reason. If the "status" is "error", an error message will be included in the response. Below is an example of a successful response.
Allow for additional fields on responses
As our API team implements new features, it is necessary to include new fields on various API services. Your integration should be flexible enough to handle additional fields on each service that were not previously returned.
Be aware of breaking changes
Our services change continually as we add new features, but we do our best to create stability so that the applications our clients build on top of our API can adapt gracefully as well.
When we introduce a breaking change, we will support two versions of the API in production, one with and one without the breaking change, for 60 days. We will announce these changes in our API Release Notes. For more details about what constitutes a breaking change, see our Breaking Changes policy.
Be mindful of object limits
Xandr limits the number of objects each member can create and use on the platform. This limit includes inactive and unused objects (e.g. campaigns set to inactive status, placements that have never served an impression, etc.). You should use the Object Limit Service to view your limits and proactively monitor your usage.