0
# API Infrastructure and Configuration
1

2
This module provides core service configuration classes for defining gRPC services with REST endpoints, authentication, quota management, and API annotations.
3

4
## Service Configuration
5

6
### Service
7

8
The main service definition containing APIs, types, documentation, and configuration.
9

10
```java { .api }
11
class Service {
12
  String getName();
13
  String getTitle();
14
  String getProducerProjectId();
15
  String getId();
16
  repeated Api getApisList();
17
  repeated Type getTypesList();
18
  repeated Enum getEnumsList();
19
  Documentation getDocumentation();
20
  Backend getBackend();
21
  Http getHttp();
22
  Quota getQuota();
23
  Authentication getAuthentication();
24
  Context getContext();
25
  Usage getUsage();
26
  repeated Endpoint getEndpointsList();
27
  Control getControl();
28
  repeated LogDescriptor getLogsList();
29
  repeated MetricDescriptor getMetricsList();
30
  repeated MonitoredResourceDescriptor getMonitoredResourcesList();
31
  Billing getBilling();
32
  Logging getLogging();
33
  Monitoring getMonitoring();
34
  SystemParameters getSystemParameters();
35
  SourceInfo getSourceInfo();
36
  UInt32Value getConfigVersion();
37
  
38
  static Service.Builder newBuilder();
39
  Service.Builder toBuilder();
40
}
41
```
42

43
### Api
44

45
Defines an API interface.
46

47
```java { .api }
48
class Api {
49
  String getName();
50
  repeated Method getMethodsList();
51
  repeated Option getOptionsList();
52
  String getVersion();
53
  SourceContext getSourceContext();
54
  repeated Mixin getMixinsList();
55
  Syntax getSyntax();
56
  
57
  static Api.Builder newBuilder();
58
}
59

60
class Method {
61
  String getName();
62
  String getRequestTypeUrl();
63
  boolean getRequestStreaming();
64
  String getResponseTypeUrl();
65
  boolean getResponseStreaming();
66
  repeated Option getOptionsList();
67
  Syntax getSyntax();
68
  
69
  static Method.Builder newBuilder();
70
}
71
```
72

73
## HTTP Configuration
74

75
### Http
76

77
Configuration for HTTP/REST API mappings.
78

79
```java { .api }
80
class Http {
81
  repeated HttpRule getRulesList();
82
  boolean getFullyDecodeReservedExpansion();
83
  
84
  static Http.Builder newBuilder();
85
}
86
```
87

88
### HttpRule
89

90
Individual HTTP mapping rule for gRPC methods.
91

92
```java { .api }
93
class HttpRule {
94
  String getSelector();
95
  String getGet();
96
  String getPost();
97
  String getPut();
98
  String getDelete();
99
  String getPatch();
100
  CustomHttpPattern getCustom();
101
  String getBody();
102
  String getResponseBody();
103
  repeated HttpRule getAdditionalBindingsList();
104
  
105
  static HttpRule.Builder newBuilder();
106
}
107

108
class CustomHttpPattern {
109
  String getKind();
110
  String getPath();
111
  
112
  static CustomHttpPattern.Builder newBuilder();
113
}
114
```
115

116
## Authentication Configuration
117

118
### Authentication
119

120
Authentication configuration for the service.
121

122
```java { .api }
123
class Authentication {
124
  repeated AuthenticationRule getRulesList();
125
  repeated AuthProvider getProvidersList();
126
  
127
  static Authentication.Builder newBuilder();
128
}
129

130
class AuthenticationRule {
131
  String getSelector();
132
  AuthRequirement getOauth();
133
  boolean getAllowWithoutCredential();
134
  repeated AuthRequirement getRequirementsList();
135
  
136
  static AuthenticationRule.Builder newBuilder();
137
}
138

139
class AuthProvider {
140
  String getId();
141
  String getIssuer();
142
  String getJwksUri();
143
  String getAudiences();
144
  String getAuthorizationUrl();
145
  repeated JwtLocation getJwtLocationsList();
146
  
147
  static AuthProvider.Builder newBuilder();
148
}
149

150
class AuthRequirement {
151
  String getProviderId();
152
  String getAudiences();
153
  
154
  static AuthRequirement.Builder newBuilder();
155
}
156
```
157

158
## Quota Management
159

160
### Quota
161

162
API quota configuration and limits.
163

164
```java { .api }
165
class Quota {
166
  repeated QuotaLimit getLimitsList();
167
  repeated MetricRule getMetricRulesList();
168
  
169
  static Quota.Builder newBuilder();
170
}
171

172
class QuotaLimit {
173
  String getName();
174
  String getDescription();
175
  long getDefaultLimit();
176
  long getMaxLimit();
177
  String getFreeTier();
178
  String getDuration();
179
  String getMetric();
180
  String getUnit();
181
  Struct getValues();
182
  String getDisplayName();
183
  
184
  static QuotaLimit.Builder newBuilder();
185
}
186

187
class MetricRule {
188
  String getSelector();
189
  Struct getMetricCosts();
190
  
191
  static MetricRule.Builder newBuilder();
192
}
193
```
194

195
## Field Behavior Annotations
196

197
### FieldBehavior
198

199
Annotations for field behavior in API definitions.
200

201
```java { .api }
202
enum FieldBehavior {
203
  FIELD_BEHAVIOR_UNSPECIFIED(0),
204
  OPTIONAL(1),
205
  REQUIRED(2),
206
  OUTPUT_ONLY(3),
207
  INPUT_ONLY(4),
208
  IMMUTABLE(5);
209
  
210
  int getNumber();
211
  static FieldBehavior forNumber(int value);
212
}
213
```
214

215
### Resource Annotations
216

217
```java { .api }
218
class ResourceDescriptor {
219
  String getType();
220
  repeated String getPatternList();
221
  String getNameField();
222
  History getHistory();
223
  String getPlural();
224
  String getSingular();
225
  repeated Style getStyleList();
226
  
227
  static ResourceDescriptor.Builder newBuilder();
228
}
229

230
class ResourceReference {
231
  String getType();
232
  String getChildType();
233
  
234
  static ResourceReference.Builder newBuilder();
235
}
236
```
237

238
## Usage Examples
239

240
### Basic Service Configuration
241

242
```java
243
// Create HTTP rule for REST endpoint
244
HttpRule getUserRule = HttpRule.newBuilder()
245
    .setSelector("myservice.MyService.GetUser")
246
    .setGet("/v1/users/{user_id}")
247
    .build();
248

249
HttpRule listUsersRule = HttpRule.newBuilder()
250
    .setSelector("myservice.MyService.ListUsers")
251
    .setGet("/v1/users")
252
    .build();
253

254
// Configure HTTP mappings
255
Http httpConfig = Http.newBuilder()
256
    .addRules(getUserRule)
257
    .addRules(listUsersRule)
258
    .setFullyDecodeReservedExpansion(true)
259
    .build();
260

261
// Create service configuration
262
Service service = Service.newBuilder()
263
    .setName("myservice.googleapis.com")
264
    .setTitle("My Service")
265
    .setHttp(httpConfig)
266
    .build();
267
```
268

269
### Authentication Setup
270

271
```java
272
// Configure OAuth provider
273
AuthProvider authProvider = AuthProvider.newBuilder()
274
    .setId("google_service_account")
275
    .setIssuer("https://accounts.google.com")
276
    .setJwksUri("https://www.googleapis.com/oauth2/v3/certs")
277
    .build();
278

279
// Create authentication rule
280
AuthenticationRule authRule = AuthenticationRule.newBuilder()
281
    .setSelector("myservice.MyService.*")
282
    .setOauth(AuthRequirement.newBuilder()
283
        .setProviderId("google_service_account")
284
        .build())
285
    .build();
286

287
// Configure authentication
288
Authentication authentication = Authentication.newBuilder()
289
    .addProviders(authProvider)
290
    .addRules(authRule)
291
    .build();
292
```
293

294
### Quota Configuration
295

296
```java
297
// Set up quota limits
298
QuotaLimit requestLimit = QuotaLimit.newBuilder()
299
    .setName("requests_per_minute")
300
    .setDescription("Requests per minute per project")
301
    .setDefaultLimit(1000)
302
    .setMaxLimit(10000)
303
    .setDuration("1m")
304
    .setMetric("myservice.googleapis.com/requests")
305
    .build();
306

307
Quota quota = Quota.newBuilder()
308
    .addLimits(requestLimit)
309
    .build();
310
```
311

312
## Service Lifecycle and Maturity
313

314
### LaunchStage
315

316
Defines the maturity level of an API or feature.
317

318
```java { .api }
319
enum LaunchStage {
320
  LAUNCH_STAGE_UNSPECIFIED(0),
321
  UNIMPLEMENTED(6),
322
  PRELAUNCH(7),
323
  EARLY_ACCESS(1),
324
  ALPHA(2),
325
  BETA(3),
326
  GA(4),
327
  DEPRECATED(5);
328
  
329
  int getNumber();
330
  static LaunchStage forNumber(int value);
331
}
332
```
333

334
### Publishing
335

336
Configuration for client library publishing and generation.
337

338
```java { .api }
339
class Publishing {
340
  repeated MethodSettings getMethodSettingsList();
341
  String getNewIssueUri();
342
  String getDocumentationUri();
343
  String getApiShortName();
344
  String getGithubLabel();
345
  repeated String getCodeownerGithubTeamsList();
346
  String getDocTagPrefix();
347
  ClientLibraryOrganization getOrganization();
348
  repeated ClientLibrarySettings getLibrarySettingsList();
349
  
350
  static Publishing.Builder newBuilder();
351
}
352

353
class MethodSettings {
354
  String getSelector();
355
  LongRunning getLongRunning();
356
  repeated String getAutoPopulatedFieldsList();
357
  
358
  static MethodSettings.Builder newBuilder();
359
}
360
```
361

362
## Monitoring and Observability
363

364
### Monitoring
365

366
Service monitoring configuration.
367

368
```java { .api }
369
class Monitoring {
370
  repeated MonitoringDestination getProducerDestinationsList();
371
  repeated MonitoringDestination getConsumerDestinationsList();
372
  
373
  static Monitoring.Builder newBuilder();
374
}
375

376
class MonitoringDestination {
377
  String getMonitoredResource();
378
  repeated String getMetricsList();
379
  
380
  static MonitoringDestination.Builder newBuilder();
381
}
382
```
383

384
### Logging
385

386
Service logging configuration.
387

388
```java { .api }
389
class Logging {
390
  repeated LoggingDestination getProducerDestinationsList();
391
  repeated LoggingDestination getConsumerDestinationsList();
392
  
393
  static Logging.Builder newBuilder();
394
}
395

396
class LoggingDestination {
397
  String getMonitoredResource();
398
  repeated String getLogsList();
399
  
400
  static LoggingDestination.Builder newBuilder();
401
}
402
```
403

404
### Visibility
405

406
API visibility controls and access restrictions.
407

408
```java { .api }
409
class Visibility {
410
  repeated VisibilityRule getRulesList();
411
  
412
  static Visibility.Builder newBuilder();
413
}
414

415
class VisibilityRule {
416
  String getSelector();
417
  String getRestriction();
418
  
419
  static VisibilityRule.Builder newBuilder();
420
}
421
```
422

423
## Extensions and Annotations
424

425
The `com.google.api` package defines several Protocol Buffer extensions for method and field annotations:
426

427
```java
428
// HTTP extension for method options
429
public static final GeneratedExtension<MethodOptions, HttpRule> http;
430

431
// Field behavior extension  
432
public static final GeneratedExtension<FieldOptions, FieldBehavior> fieldBehavior;
433

434
// Resource reference extension
435
public static final GeneratedExtension<FieldOptions, ResourceReference> resourceReference;
436

437
// Resource definition extension
438
public static final GeneratedExtension<MessageOptions, ResourceDescriptor> resource;
439
```
440

441
These extensions are used in `.proto` files to annotate methods and fields with HTTP mappings, field behaviors, and resource relationships.