Background

Before you start

1. Ask your account representative to set up proper permissions for accounts your application will access.
2. If you're unfamiliar with Authorized Buyers concepts, visit the Authorized Buyers Help Center and experiment with the user interface. If your application is expected to perform real-time bidding, read the RTB Protocol documentation.
3. Visit the APIs Console to set up a new project. Either sign in to your developer Google account or create an account. You will then be prompted to create a project and sign off on a couple of Terms of Service.

Parent and child accounts

If you're working within an account structure containing parent and child accounts, you may be able to work more effectively if you understand how they interact. The following is a brief summary:

Child accounts

A user with credentials that grant access to a child account can only view and modify resources associated with their account. Child accounts can't view or modify resources belonging to other child or parent accounts.

Parent accounts

A user with credentials that grant access to a parent account can view and modify resources for the parent account in addition to all associated child accounts. For operations listing all of a given resource, this user will receive a response including data for their account and all of their child accounts. Note that for other types of requests targeting resources for child seats, a parent account will need to specify an accountId path parameter for the child account rather than their own accountId.

Note: You should contact your Technical Account Manager if you want to configure an account structure with parent and child accounts.

The REST API data model

A resource is an individual data entity with a unique identifier. The Accounts resource represents an Authorized Buyers account entry, and is the root data class for the Ad Exchange Buyer API. The API's methods operate on individual Accounts resources, and on collections of Accounts resources.

An Accounts Resource includes: an Account ID, information used in cookie matching, bidder locations, the URL to which bid requests are sent, and a request to specify the maximum queries per second to be sent by the ad exchange.

In addition to the Accounts resource and collection, the Ad Exchange Buyer API defines the following data structures:

Bidder location

Bidder locations are structures that are returned with Accounts Resources to provide the URL to which the ad exchange should send bid requests and the maximum number of queries per second the ad exchange should send. Here is an example of a bidder location, expressed in JSON:

"bidderLocation": [
    {
      "url": "http://bid.url.com/bidder",
      "maximumQps": 1500
    }
  ],

Items

Items provide a list of accounts. Here is an example of items, expressed in JSON:

{
  "kind": "adexchangebuyer#accountsList",
  "items": [
    accounts Resource
  ]
}

Supported operations

You can invoke three different methods on collections and resources in the Ad Exchange Buyer API as described in the following table. All operations require authorization.

Operation	Description	REST HTTP mappings
list	Lists all accounts that can be accessed by the currently authenticated user.	GET on a collection URI.
get	Gets a specific Accounts resource.	GET on a resource URI.
update	Updates a specific Accounts resource.	PUT on a resource URI, where you pass in data for the updated resource.

Calling style

REST is a style of software architecture that provides a convenient and consistent approach to requesting and modifying data.

The term REST is short for "Representational State Transfer." In the context of Google APIs, it refers to using HTTP verbs to retrieve and modify representations of data stored by Google.

In a RESTful system, resources are stored in a data store; a client sends a request that the server perform a particular action (such as creating, retrieving, updating, or deleting a resource), and the server performs the action and sends a response, often in the form of a representation of the specified resource.

In Google's RESTful APIs, the client specifies an action using an HTTP verb such as POST, GET, PUT, or DELETE. It specifies a resource by a globally-unique URI of the following form:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Because all API resources have unique HTTP-accessible URIs, REST enables data caching and is optimized to work with the web's distributed infrastructure.

You may find the method definitions in the HTTP 1.1 standards documentation useful; they include specifications for GET, POST, PUT, and DELETE.

REST in the Ad Exchange Buyer API

The supported operations map directly to REST HTTP verbs, as described in API operations.

The specific format for API URIs are:

https://www.googleapis.com/adexchangebuyer/v1.4/resourceID?parameters

where resourceID is the identifier for an Accounts resource, and parameters are any parameters to apply to the query. See standard query parameters and the reference documentation for details.

The format of the resourceID path extensions lets you identify the resource you're currently operating on, for example:

https://www.googleapis.com/adexchangebuyer/v1.4/accounts
https://www.googleapis.com/adexchangebuyer/v1.4/accounts/id

The full set of URIs used for each supported operation in the API is summarized in the reference documentation.

Here's an example of how this works in the Ad Exchange Buyer API.

Get the authenticated user's list of accounts:

GET https://www.googleapis.com/adexchangebuyer/v1.4/accounts

Data format

JSON

JSON (JavaScript Object Notation) is a common, language-independent data format that provides a simple text representation of arbitrary data structures. For more information, see json.org.