0
# API Framework Types
1

2
Core infrastructure types for Google API definition including field behaviors, resource patterns, authentication, HTTP mapping, and client library configuration. These types enable consistent API design and automatic client generation across Google services.
3

4
## Capabilities
5

6
### Field Behavior Annotations
7

8
Annotations that specify field requirements and constraints in API definitions.
9

10
```python { .api }
11
from google.api.field_behavior_pb2 import FieldBehavior
12

13
class FieldBehavior(enum.Enum):
14
    """Field behavior enumeration values."""
15
    FIELD_BEHAVIOR_UNSPECIFIED = 0
16
    OPTIONAL = 1
17
    REQUIRED = 2
18
    OUTPUT_ONLY = 3
19
    INPUT_ONLY = 4
20
    IMMUTABLE = 5
21
    UNORDERED_LIST = 6
22
    NON_EMPTY_DEFAULT = 7
23
    IDENTIFIER = 8
24
```
25

26
### Launch Stage Annotations
27

28
API maturity level annotations for features and services.
29

30
```python { .api }
31
from google.api.launch_stage_pb2 import LaunchStage
32

33
class LaunchStage(enum.Enum):
34
    """API maturity levels."""
35
    LAUNCH_STAGE_UNSPECIFIED = 0
36
    UNIMPLEMENTED = 1
37
    PRELAUNCH = 2
38
    EARLY_ACCESS = 3
39
    ALPHA = 4
40
    BETA = 5
41
    GA = 6
42
    DEPRECATED = 7
43
```
44

45
### Resource Management
46

47
Define API resources with patterns, naming conventions, and relationships.
48

49
```python { .api }
50
from google.api.resource_pb2 import ResourceDescriptor, ResourceReference
51

52
class ResourceDescriptor(message.Message):
53
    """Defines a resource type."""
54
    type: str  # Resource type identifier
55
    pattern: list[str]  # URI pattern templates
56
    name_field: str  # Field containing resource name
57
    history: ResourceDescriptor.History
58
    plural: str  # Plural form of resource name
59
    singular: str  # Singular form of resource name
60
    style: list[ResourceDescriptor.Style]
61

62
    class History(enum.Enum):
63
        HISTORY_UNSPECIFIED = 0
64
        ORIGINALLY_SINGLE_PATTERN = 1
65
        FUTURE_MULTI_PATTERN = 2
66

67
    class Style(enum.Enum):
68
        STYLE_UNSPECIFIED = 0
69
        DECLARATIVE_FRIENDLY = 1
70

71
class ResourceReference(message.Message):
72
    """References another resource type."""
73
    type: str  # Referenced resource type
74
    child_type: str  # Child resource type
75
```
76

77
### HTTP Rule Mapping
78

79
Map gRPC service methods to HTTP/REST endpoints.
80

81
```python { .api }
82
from google.api.http_pb2 import Http, HttpRule, CustomHttpPattern
83

84
class Http(message.Message):
85
    """HTTP configuration for a service."""
86
    rules: list[HttpRule]
87
    fully_decode_reserved_expansion: bool
88

89
class HttpRule(message.Message):
90
    """HTTP rule for mapping RPC methods to HTTP endpoints."""
91
    selector: str  # RPC method selector
92
    get: str  # HTTP GET pattern
93
    put: str  # HTTP PUT pattern  
94
    post: str  # HTTP POST pattern
95
    delete: str  # HTTP DELETE pattern
96
    patch: str  # HTTP PATCH pattern
97
    custom: CustomHttpPattern  # Custom HTTP method
98
    body: str  # HTTP request body field
99
    response_body: str  # HTTP response body field
100
    additional_bindings: list[HttpRule]  # Additional HTTP bindings
101

102
class CustomHttpPattern(message.Message):
103
    """Custom HTTP method pattern."""
104
    kind: str  # HTTP method name
105
    path: str  # URL path pattern
106
```
107

108
### Authentication Configuration
109

110
Configure authentication and authorization for API services.
111

112
```python { .api }
113
from google.api.auth_pb2 import (
114
    Authentication, AuthenticationRule, AuthProvider, 
115
    JwtLocation, OAuthRequirements, AuthRequirement
116
)
117

118
class Authentication(message.Message):
119
    """Authentication configuration for a service."""
120
    rules: list[AuthenticationRule]
121
    providers: list[AuthProvider]
122

123
class AuthenticationRule(message.Message):
124
    """Authentication rule for specific methods."""
125
    selector: str  # Method selector pattern
126
    oauth: OAuthRequirements  # OAuth configuration
127
    allow_without_credential: bool  # Allow unauthenticated access
128
    requirements: list[AuthRequirement]  # Authentication requirements
129

130
class AuthProvider(message.Message):
131
    """Authentication provider configuration."""
132
    id: str  # Provider identifier
133
    issuer: str  # Token issuer
134
    jwks_uri: str  # JSON Web Key Set URI
135
    audiences: str  # Valid audiences
136
    authorization_url: str  # Authorization endpoint
137
    jwt_locations: list[JwtLocation]  # JWT token locations
138

139
class JwtLocation(message.Message):
140
    """Location of JWT token in request."""
141
    header: str  # HTTP header name
142
    query: str  # Query parameter name
143
    cookie: str  # Cookie name
144
    value_prefix: str  # Token value prefix
145

146
class OAuthRequirements(message.Message):
147
    """OAuth requirements configuration."""
148
    canonical_scopes: str  # Required OAuth scopes
149

150
class AuthRequirement(message.Message):
151
    """Authentication requirement."""
152
    provider_id: str  # Provider identifier
153
    audiences: str  # Required audiences
154
```
155

156
### Client Library Configuration
157

158
Configure automatic client library generation settings.
159

160
```python { .api }
161
from google.api.client_pb2 import (
162
    CommonLanguageSettings, ClientLibrarySettings, Publishing,
163
    MethodSettings, ClientLibraryOrganization, ClientLibraryDestination
164
)
165

166
class ClientLibraryOrganization(enum.Enum):
167
    """Client library organization types."""
168
    CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED = 0
169
    CLOUD = 1
170
    ADS = 2
171
    PHOTOS = 3
172
    STREET_VIEW = 4
173
    SHOPPING = 5
174
    GEO = 6
175
    GENERATIVE_AI = 7
176

177
class ClientLibraryDestination(enum.Enum):
178
    """Client library publication destinations."""
179
    CLIENT_LIBRARY_DESTINATION_UNSPECIFIED = 0
180
    GITHUB = 10
181
    PACKAGE_MANAGER = 20
182

183
class CommonLanguageSettings(message.Message):
184
    """Common settings for all language generators."""
185
    reference_docs_uri: str  # Reference documentation URL
186
    destinations: list[ClientLibraryDestination]  # Publication destinations
187

188
class ClientLibrarySettings(message.Message):
189
    """Client library generation settings."""
190
    version: str  # Library version
191
    launch_stage: LaunchStage  # API maturity stage
192
    rest_numeric_enums: bool  # Use numeric enums in REST
193
    java_settings: JavaSettings  # Java-specific settings
194
    cpp_settings: CppSettings  # C++ specific settings
195
    php_settings: PhpSettings  # PHP-specific settings
196
    python_settings: PythonSettings  # Python-specific settings
197
    node_settings: NodeSettings  # Node.js-specific settings
198
    dotnet_settings: DotnetSettings  # .NET-specific settings
199
    ruby_settings: RubySettings  # Ruby-specific settings
200
    go_settings: GoSettings  # Go-specific settings
201

202
class MethodSettings(message.Message):
203
    """Method-specific client settings."""
204
    selector: str  # Method selector pattern
205
    long_running: MethodSettings.LongRunning  # Long-running operation config
206
    auto_populated_fields: list[str]  # Auto-populated field names
207

208
    class LongRunning(message.Message):
209
        """Long-running operation settings."""
210
        initial_poll_delay: Duration  # Initial polling delay
211
        poll_delay_multiplier: float  # Delay multiplier
212
        max_poll_delay: Duration  # Maximum polling delay
213
        total_poll_timeout: Duration  # Total timeout
214
```
215

216
### Launch Stages and Visibility
217

218
Define API maturity levels and visibility rules.
219

220
```python { .api }
221
from google.api.launch_stage_pb2 import LaunchStage
222
from google.api.visibility_pb2 import Visibility, VisibilityRule
223

224
class LaunchStage(enum.Enum):
225
    """API launch stage enumeration."""
226
    LAUNCH_STAGE_UNSPECIFIED = 0
227
    UNIMPLEMENTED = 6
228
    PRELAUNCH = 7
229
    EARLY_ACCESS = 1
230
    ALPHA = 2
231
    BETA = 3
232
    GA = 4
233
    DEPRECATED = 5
234

235
class Visibility(message.Message):
236
    """API visibility configuration."""
237
    rules: list[VisibilityRule]
238

239
class VisibilityRule(message.Message):
240
    """Visibility rule for API elements."""
241
    selector: str  # Element selector pattern
242
    restriction: str  # Visibility restriction
243
```
244

245
### Service Configuration
246

247
Complete API service definition and configuration.
248

249
```python { .api }
250
from google.api.service_pb2 import Service
251
from google.api.usage_pb2 import Usage, UsageRule
252
from google.api.quota_pb2 import Quota, QuotaLimit, MetricRule
253
from google.api.billing_pb2 import Billing, BillingDestination
254

255
class Service(message.Message):
256
    """Complete API service configuration."""
257
    name: str  # Service name
258
    title: str  # Service title
259
    producer_project_id: str  # Producer project ID
260
    id: str  # Service ID
261
    apis: list[Api]  # Service APIs
262
    types: list[Type]  # Custom types
263
    enums: list[Enum]  # Custom enums
264
    documentation: Documentation  # Documentation config
265
    backend: Backend  # Backend configuration
266
    http: Http  # HTTP configuration
267
    quota: Quota  # Quota configuration
268
    authentication: Authentication  # Auth configuration
269
    context: Context  # Context configuration
270
    usage: Usage  # Usage configuration
271
    endpoints: list[Endpoint]  # Service endpoints
272
    control: Control  # Service control config
273
    logs: list[LogDescriptor]  # Log descriptors
274
    metrics: list[MetricDescriptor]  # Metric descriptors
275
    monitored_resources: list[MonitoredResourceDescriptor]  # Monitored resources
276
    billing: Billing  # Billing configuration
277
    logging: Logging  # Logging configuration
278
    monitoring: Monitoring  # Monitoring configuration
279
    system_parameters: SystemParameters  # System parameters
280
    source_info: SourceInfo  # Source information
281

282
class Usage(message.Message):
283
    """API usage configuration."""
284
    requirements: list[str]  # Usage requirements
285
    rules: list[UsageRule]  # Usage rules
286
    producer_notification_channel: str  # Notification channel
287

288
class Quota(message.Message):
289
    """Quota configuration."""
290
    limits: list[QuotaLimit]  # Quota limits
291
    metric_rules: list[MetricRule]  # Metric rules
292

293
class Billing(message.Message):
294
    """Billing configuration."""
295
    consumer_destinations: list[BillingDestination]  # Consumer billing destinations
296
```
297

298
### Labels and Metadata
299

300
Define labels and field information for API elements.
301

302
```python { .api }
303
from google.api.label_pb2 import LabelDescriptor
304
from google.api.field_info_pb2 import FieldInfo
305

306
class LabelDescriptor(message.Message):
307
    """Label descriptor."""
308
    key: str  # Label key
309
    value_type: LabelDescriptor.ValueType  # Value type
310
    description: str  # Label description
311

312
    class ValueType(enum.Enum):
313
        STRING = 0
314
        BOOL = 1
315
        INT64 = 2
316

317
class FieldInfo(message.Message):
318
    """Field information and formatting."""
319
    format: FieldInfo.Format  # Field format
320
    referenced_types: list[TypeReference]  # Referenced types
321

322
    class Format(enum.Enum):
323
        FORMAT_UNSPECIFIED = 0
324
        UUID4 = 1
325
        IPV4 = 2
326
        IPV6 = 3
327
        IPV4_OR_IPV6 = 4
328
```
329

330
## Usage Examples
331

332
### Resource Definition
333

334
```python
335
from google.api.resource_pb2 import ResourceDescriptor
336

337
# Define a resource type
338
resource = ResourceDescriptor()
339
resource.type = "example.googleapis.com/Book"
340
resource.pattern.extend([
341
    "publishers/{publisher}/books/{book}",
342
    "projects/{project}/books/{book}"
343
])
344
resource.name_field = "name"
345
resource.plural = "books"
346
resource.singular = "book"
347
```
348

349
### HTTP Rule Configuration
350

351
```python
352
from google.api.http_pb2 import HttpRule
353

354
# Map RPC method to HTTP endpoint
355
rule = HttpRule()
356
rule.selector = "google.example.Library.GetBook"
357
rule.get = "/v1/{name=publishers/*/books/*}"
358
```
359

360
### Authentication Setup
361

362
```python
363
from google.api.auth_pb2 import Authentication, AuthenticationRule
364

365
# Configure service authentication
366
auth = Authentication()
367
rule = AuthenticationRule()
368
rule.selector = "google.example.Library.*"
369
rule.oauth.canonical_scopes = "https://www.googleapis.com/auth/cloud-platform"
370
auth.rules.append(rule)
371
```