feat: add api_version extension to ServiceOptions, for collaborative versioning

Google APIs · copybara-github · commit dba3883bfb92 · 2024-03-08T08:58:20.000-08:00
feat: add `Publishing.rest_reference_documentation_uri` to aid client library publication
feat: add `ErrorReason.LOCATION_POLICY_VIOLATED` enum value
docs: minor tweaks to various comments

PiperOrigin-RevId: 613949885
diff --git a/google/api/client.proto b/google/api/client.proto
@@ -98,6 +98,22 @@ extend google.protobuf.ServiceOptions {
   //     ...
   //   }
   string oauth_scopes = 1050;
+
+  // The API version of this service, which should be sent by version-aware
+  // clients to the service. This allows services to abide by the schema and
+  // behavior of the service at the time this API version was deployed.
+  // The format of the API version must be treated as opaque by clients.
+  // Services may use a format with an apparent structure, but clients must
+  // not rely on this to determine components within an API version, or attempt
+  // to construct other valid API versions. Note that this is for upcoming
+  // functionality and may not be implemented for all services.
+  //
+  // Example:
+  //
+  //   service Foo {
+  //     option (google.api.api_version) = "v1_20230821_preview";
+  //   }
+  string api_version = 525000001;
 }
 
 // Required information for every language.
@@ -192,6 +208,10 @@ message Publishing {
   // Optional link to proto reference documentation.  Example:
   // https://cloud.google.com/pubsub/lite/docs/reference/rpc
   string proto_reference_documentation_uri = 110;
+
+  // Optional link to REST reference documentation.  Example:
+  // https://cloud.google.com/pubsub/lite/docs/reference/rest
+  string rest_reference_documentation_uri = 111;
 }
 
 // Settings for Java client libraries.
diff --git a/google/api/documentation.proto b/google/api/documentation.proto
@@ -34,7 +34,7 @@ option objc_class_prefix = "GAPI";
 //     content: &#40;== include google/foo/overview.md ==&#41;
 //   - name: Tutorial
 //     content: &#40;== include google/foo/tutorial.md ==&#41;
-//     subpages;
+//     subpages:
 //     - name: Java
 //       content: &#40;== include google/foo/tutorial_java.md ==&#41;
 //   rules:
diff --git a/google/api/error_reason.proto b/google/api/error_reason.proto
@@ -567,4 +567,23 @@ enum ErrorReason {
   //
   // This response indicates the associated GCP account has been suspended.
   GCP_SUSPENDED = 30;
+
+  // The request violates the location policies when creating resources in
+  // the restricted region.
+  //
+  // Example of an ErrorInfo when creating the Cloud Storage Bucket by
+  // "projects/123" for service storage.googleapis.com:
+  //
+  //     { "reason": "LOCATION_POLICY_VIOLATED",
+  //       "domain": "googleapis.com",
+  //       "metadata": {
+  //         "consumer": "projects/123",
+  //         "service": "storage.googleapis.com",
+  //       }
+  //     }
+  //
+  // This response indicates creating the Cloud Storage Bucket in
+  // "locations/asia-northeast3" violates at least one location policy.
+  // The troubleshooting guidance is provided in the Help links.
+  LOCATION_POLICY_VIOLATED = 31;
 }
diff --git a/google/api/field_info.proto b/google/api/field_info.proto
@@ -61,9 +61,9 @@ message FieldInfo {
 
     // Internet Protocol v6 value as defined by [RFC
     // 2460](https://datatracker.ietf.org/doc/html/rfc2460). The value may be
-    // normalized to entirely lowercase letters, and zero-padded partial and
-    // empty octets. For example, the value `2001:DB8::` would be normalized to
-    // `2001:0db8:0:0`.
+    // normalized to entirely lowercase letters with zeros compressed, following
+    // [RFC 5952](https://datatracker.ietf.org/doc/html/rfc5952). For example,
+    // the value `2001:0DB8:0::0` would be normalized to `2001:db8::`.
     IPV6 = 3;
 
     // An IP address in either v4 or v6 format as described by the individual
diff --git a/google/api/monitored_resource.proto b/google/api/monitored_resource.proto
@@ -49,7 +49,7 @@ message MonitoredResourceDescriptor {
 
   // Required. The monitored resource type. For example, the type
   // `"cloudsql_database"` represents databases in Google Cloud SQL.
-  //  For a list of types, see [Monitoring resource
+  //  For a list of types, see [Monitored resource
   //  types](https://cloud.google.com/monitoring/api/resources)
   // and [Logging resource
   // types](https://cloud.google.com/logging/docs/api/v2/resource-list).
