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.

Resource-oriented 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 using 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/v21/customers/1234567890:mutate 

All REST URLs for a particular version of the API (e.g., v21 ) 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.