Best Practices

This page covers various best practices that should be considered when developing applications against the Google Ad Manager API.

Reuse service clients/stubs during the course of an execution

Creating a new service client/stub has a marginal cost associated with fetching the WSDL and allocating resources. If possible, create the service client/stub once at the beginning of an execution and make it available to classes and functions as needed.

Use paging when fetching objects

All of the services support a get*ByStatement() method, which allows for the filtering of results using PQL syntax. The LIMIT and OFFSET clauses can be used to split large result sets into pages, preventing time outs and keeping the response page sizes reasonable. The suggested page size is 200-500, depending on the complexity of your objects.

Batch update requests

When changing multiple objects of the same type, you can get better performance by sending all of the objects in the same update*() request. There is a marginal overhead on the client and the server for each request, and batching can be an effective means of reducing the number of requests. For example, use updateOrders to update a batch of Orders rather than a single order in each call.

Use bind parameters in PQL

Bind parameters are a way to put variables into a PQL query statement. PQL refers to a bind variable by a name without spaces starting with a colon, e.g., :name. A code example is provided in the PQL syntax page.

We recommend using bind variables because they improve code readability by removing the need to concatenate strings and variables into a query statement. They also make it easy to reuse PQL statements, since new queries can be made by substituting the bind parameter values.

Grant user privileges sparingly

When using UserService to create/update user roles, be careful not to grant users privileges they do not need. Many features of the API can be accessed with a combination of roles rather than assigning the user an administrator role. Please refer to the permissions documentation when deciding which roles to assign a user. Also, as a third party application developer, make sure to determine what level of access your application needs when asking a network to create a user for you; a role with fewer privileges than administrator may be enough.

Stay under quota limits

The Ad Manager API enforces several quota limits for robustness. It's important to keep your applications under these limits and that you know how to respond to any of the quota errors the API can return.

API quota

The first quota applied to API requests is a network-level quota. For Ad Manager 360 accounts, the limit is 8 requests per second, and for Ad Manager accounts, the limit is 2 requests per second. Going beyond this limit results in a QuotaError.EXCEEDED_QUOTA error. All API requests made on your network apply to this quota, including third-party applications that you or someone at your company has granted API access to your network.

System-specific quotas

The API quota alone is not enough to adequately protect certain resource-intensive systems within Ad Manager. The reporting and forecast systems define their own quotas that can result in API errors: QuotaError.REPORT_JOB_LIMIT and ForecastError.EXCEEDED_QUOTA, respectively.

Handling quota errors

If your application encounters any of the above quota errors, carry out a strategy for retrying the API request. We recommend waiting at least 5 seconds first, and if you continue to get the error, use exponential backoff to increase the time between retries. If retrying doesn't succeed, perform an audit of your API applications to see if any users on your network are draining your quota.