0
# API Discovery and Service Building
1

2
The discovery module provides the core functionality for dynamically building Google API service clients. It fetches API discovery documents, generates Python classes and methods, and handles authentication integration.
3

4
## Capabilities
5

6
### Service Building
7

8
Create service clients for Google APIs with automatic method generation and authentication.
9

10
```python { .api }
11
def build(serviceName, version, http=None, discoveryServiceUrl=None, 
12
          developerKey=None, model=None, requestBuilder=None, 
13
          credentials=None, cache_discovery=True, cache=None, 
14
          client_options=None, adc_cert_path=None, adc_key_path=None, 
15
          num_retries=1, static_discovery=None, always_use_jwt_access=False):
16
    """
17
    Construct a Resource for interacting with an API.
18
    
19
    Args:
20
        serviceName (str): Name of the service (e.g., 'gmail', 'drive', 'youtube')
21
        version (str): Version of the service (e.g., 'v1', 'v2', 'v3')
22
        http (httplib2.Http, optional): HTTP client instance for requests
23
        discoveryServiceUrl (str, optional): URL for the discovery service
24
        developerKey (str, optional): API key for public API access
25
        model (BaseModel, optional): Data model for request/response handling  
26
        requestBuilder (RequestBuilder, optional): Custom request builder
27
        credentials (Credentials, optional): OAuth2 credentials for authenticated requests
28
        cache_discovery (bool): Whether to cache discovery documents (default: True)
29
        cache (Cache, optional): Custom cache implementation for discovery documents
30
        client_options (ClientOptions, optional): Client configuration options
31
        adc_cert_path (str, optional): Path to Application Default Credentials certificate
32
        adc_key_path (str, optional): Path to Application Default Credentials private key
33
        num_retries (int): Number of retry attempts for discovery document retrieval (default: 1)
34
        static_discovery (bool, optional): Use static discovery documents when available (None for auto-detection)
35
        always_use_jwt_access (bool): Always use JWT access tokens for service account credentials (default: False)
36
        
37
    Returns:
38
        Resource: A Resource object with dynamically generated methods for each API endpoint
39
        
40
    Raises:
41
        UnknownApiNameOrVersion: When the specified API name or version is not found
42
        HttpError: When the discovery document cannot be retrieved
43
    """
44

45
def build_from_document(service, base=None, future=None, http=None, 
46
                       developerKey=None, model=None, requestBuilder=None, 
47
                       credentials=None, client_options=None, adc_cert_path=None, 
48
                       adc_key_path=None, always_use_jwt_access=False):
49
    """
50
    Create a Resource from a discovery document.
51
    
52
    Args:
53
        service (dict or str): The discovery document as a Python dictionary or JSON string
54
        base (str, optional): Base URI for the service endpoints (deprecated)
55
        future (str, optional): Future version identifier for experimental features (deprecated)
56
        developerKey (str, optional): API key for public API access
57
        http (httplib2.Http, optional): HTTP client instance for requests
58
        model (BaseModel, optional): Data model for request/response handling
59
        requestBuilder (RequestBuilder, optional): Custom request builder implementation
60
        credentials (Credentials, optional): OAuth2 credentials for authenticated requests
61
        client_options (ClientOptions, optional): Client configuration options
62
        adc_cert_path (str, optional): Path to Application Default Credentials certificate
63
        adc_key_path (str, optional): Path to Application Default Credentials private key
64
        always_use_jwt_access (bool): Always use JWT access tokens for service account credentials (default: False)
65
        
66
    Returns:
67
        Resource: A Resource object built from the provided discovery document
68
        
69
    Raises:
70
        ValueError: When the discovery document is malformed or incomplete
71
    """
72
```
73

74
### Discovery Document Access
75

76
Retrieve and process Google API discovery documents.
77

78
```python { .api }
79
def key2param(key):
80
    """
81
    Convert a discovery document key to a Python parameter name.
82
    
83
    Args:
84
        key (str): Key from discovery document
85
        
86
    Returns:
87
        str: Python-safe parameter name
88
    """
89

90
def fix_method_name(name):
91
    """
92
    Convert an API method name to Python naming convention.
93
    
94
    Args:
95
        name (str): Method name from discovery document
96
        
97
    Returns:
98
        str: Python-compatible method name
99
    """
100
```
101

102
### Discovery Constants
103

104
```python { .api }
105
DISCOVERY_URI = "https://www.googleapis.com/discovery/v1/apis/{api}/{apiVersion}/rest"
106
V1_DISCOVERY_URI = "https://www.googleapis.com/discovery/v1/apis/{api}/{apiVersion}/rest" 
107
V2_DISCOVERY_URI = "https://{api}.googleapis.com/$discovery/rest?version={apiVersion}"
108

109
# Environment variables for mTLS configuration
110
GOOGLE_API_USE_CLIENT_CERTIFICATE = "GOOGLE_API_USE_CLIENT_CERTIFICATE"
111
GOOGLE_API_USE_MTLS_ENDPOINT = "GOOGLE_API_USE_MTLS_ENDPOINT"
112
GOOGLE_CLOUD_UNIVERSE_DOMAIN = "GOOGLE_CLOUD_UNIVERSE_DOMAIN"
113
DEFAULT_UNIVERSE = "googleapis.com"
114

115
# HTTP and parameter processing constants
116
HTTP_PAYLOAD_METHODS = frozenset(["PUT", "POST", "PATCH"])
117
STACK_QUERY_PARAMETERS = frozenset(["trace", "pp", "userip", "strict"])
118
RESERVED_WORDS = frozenset(["body"])
119
DEFAULT_METHOD_DOC = "A description of how to use this function"
120
```
121

122
### Resource Classes
123

124
Dynamic API resource classes generated from discovery documents.
125

126
```python { .api }
127
class Resource:
128
    """
129
    A class for interacting with a resource.
130
    
131
    Methods are dynamically generated based on the discovery document and provide
132
    typed access to API endpoints with proper parameter validation and authentication.
133
    """
134
    
135
    def __init__(self, http, baseUrl, model, requestBuilder, developerKey, 
136
                 resourceDesc, rootDesc, schema, universe_domain="googleapis.com"):
137
        """
138
        Initialize a Resource object.
139
        
140
        Args:
141
            http (httplib2.Http): Object to make HTTP requests
142
            baseUrl (str): Base URL for the API
143
            model (googleapiclient.Model): Wire format converter
144
            requestBuilder (callable): HttpRequest object instantiator
145
            developerKey (str): API key from Google APIs Console
146
            resourceDesc (dict): Section of discovery document describing resource
147
            rootDesc (dict): Entire deserialized discovery document
148
            schema (dict): Mapping of schema names to descriptions
149
            universe_domain (str): Universe for the API (default: "googleapis.com")
150
        """
151
    
152
    def close(self):
153
        """
154
        Close httplib2 connections.
155
        """
156
    
157
    def __enter__(self):
158
        """
159
        Context manager entry.
160
        
161
        Returns:
162
            Resource: Self for context management
163
        """
164
    
165
    def __exit__(self, exc_type, exc_val, exc_tb):
166
        """
167
        Context manager exit with connection cleanup.
168
        """
169
    
170
    def new_batch_http_request(self, callback=None):
171
        """
172
        Create a BatchHttpRequest object (only available on root resources).
173
        
174
        Args:
175
            callback (callable, optional): Default callback for batch requests
176
            
177
        Returns:
178
            BatchHttpRequest: Batch request object for combining multiple requests
179
        """
180

181
class ResourceMethodParameters:
182
    """
183
    Represents the parameters associated with a method.
184
    
185
    Stores metadata about API method parameters including validation rules,
186
    location information, and parameter types extracted from discovery documents.
187
    """
188
    
189
    def __init__(self, method_desc):
190
        """
191
        Initialize method parameters from discovery document.
192
        
193
        Args:
194
            method_desc (dict): Dictionary with metadata describing an API method
195
        """
196
    
197
    def set_parameters(self, method_desc):
198
        """
199
        Populate parameter maps and lists based on method description.
200
        
201
        Args:
202
            method_desc (dict): Method description from discovery document
203
        """
204

205
class APICoreVersionError(ValueError):
206
    """
207
    Raised when google-api-core >= 2.18.0 is required for universe domain features.
208
    
209
    This error occurs when attempting to use universe domain functionality
210
    without the required version of google-api-core installed.
211
    """
212
```
213

214
## Usage Examples
215

216
### Basic Service Building
217

218
```python
219
from googleapiclient import discovery
220
import google.auth
221

222
# Build Gmail service with default credentials
223
credentials, project = google.auth.default()
224
gmail_service = discovery.build('gmail', 'v1', credentials=credentials)
225

226
# Build YouTube service with API key (for public data)
227
youtube_service = discovery.build('youtube', 'v3', developerKey='YOUR_API_KEY')
228

229
# Build Drive service with custom HTTP client
230
import httplib2
231
http = httplib2.Http()
232
drive_service = discovery.build('drive', 'v3', http=http, credentials=credentials)
233
```
234

235
### Service Building with Custom Configuration
236

237
```python
238
from googleapiclient import discovery
239
from googleapiclient.discovery_cache.file_cache import Cache
240
from google.api_core.client_options import ClientOptions
241

242
# Build service with custom cache
243
cache = Cache(max_age=3600)  # 1 hour cache
244
service = discovery.build(
245
    'gmail', 
246
    'v1', 
247
    credentials=credentials, 
248
    cache=cache,
249
    cache_discovery=True
250
)
251

252
# Build service with client options
253
client_options = ClientOptions(api_endpoint='https://custom-endpoint.googleapis.com')
254
service = discovery.build(
255
    'customsearch', 
256
    'v1', 
257
    credentials=credentials,
258
    client_options=client_options
259
)
260
```
261

262
### Building from Discovery Document
263

264
```python
265
import json
266
from googleapiclient import discovery
267

268
# Load discovery document from file
269
with open('gmail-v1-discovery.json', 'r') as f:
270
    discovery_doc = json.load(f)
271

272
# Build service from document
273
service = discovery.build_from_document(
274
    discovery_doc, 
275
    credentials=credentials
276
)
277
```
278

279
### Error Handling During Service Building
280

281
```python
282
from googleapiclient import discovery, errors
283

284
try:
285
    service = discovery.build('unknown-api', 'v1', credentials=credentials)
286
except errors.UnknownApiNameOrVersion as e:
287
    print(f"API not found: {e}")
288
except errors.HttpError as e:
289
    print(f"HTTP error during discovery: {e}")
290
```
291

292
### Working with Generated Resource Methods
293

294
```python
295
# Build service
296
service = discovery.build('gmail', 'v1', credentials=credentials)
297

298
# Access nested resources and methods
299
messages_resource = service.users().messages()
300

301
# Call methods (returns HttpRequest objects)
302
list_request = messages_resource.list(userId='me', maxResults=10)
303
get_request = messages_resource.get(userId='me', id='message_id')
304

305
# Execute requests
306
messages = list_request.execute()
307
message = get_request.execute()
308
```