REST Interface Design

This page assumes a familiarity with the Resource Oriented Design and Resource Names developer guides and complements them with specific implementation details of the Google Ads API.

Discovery document

A discovery document is a machine-readable specification for describing and consuming the Google Ads API's REST interface. It provides metadata that describes the services and resources of the API and can be helpful for generating client libraries, IDE plugins, and other tools that interact with the API. You can retrieve the discovery document for specific versions of the API at the following URL:

https://googleads.googleapis.com/$discovery/rest

Filter to a specific version of the API (for example, v5) by specifying the version parameter in the URL:

https://googleads.googleapis.com/$discovery/rest?version=v5

Google Ads API design

Generally, the Google Ads API follows a resource-oriented design, modeled as collections of individually-addressable resources (the nouns of the API). Resources are referenced with their resource names and manipulated via a small set of methods (also known as verbs or operations).

These resource names and methods, combined with a specific API version prefix, comprise the URLs of the REST interface. For example, the URL below can be broken down into these individual components according to the following table:

https://googleads.googleapis.com/v5/customers/1234567890:mutate
API Version Prefix Resource Name (relative) Method
https://googleads.googleapis.com/v5 customers/1234567890 mutate

All REST URLs for a particular version of the API (e.g., v5) share a common API version prefix. The resource name and method together identifies which API service is being called.

The Google Ads API makes heavy use of custom methods, as opposed to most traditional REST APIs that use standard REST methods such as list, get, create, update, and delete. Examples of custom methods in the Google Ads API include search, searchStream, and mutate.

The following pages go into more details about the Google Ads API's resource names, service methods, and JSON naming conventions to illustrate how they're used together to define REST interface endpoints.