feat(AIP-4235): automatically populate fields in the request message

aip/client-libraries/4235.md

@@ -0,0 +1,62 @@
+---
+id: 4235
+state: draft
+created: 2024-02-15
+---
+
+# Automatically populate fields in the request message
+
+For APIs that leverage request idempotency as described via [AIP-155], it could
+be useful to have the client libraries automatically populate the `request_id`
+if it is
+not already set by the customer.
+
+**Note:** This feature is primarily written for `request_id` fields within the
+request message. However, this feature should work for a field of any name, as
+long as the below conditions hold true.
+
+## Guidance
+
+APIs **may** configure fields in the request message for automatic population.
+
+For a field to be automatically populated, the below configurations **must** be
+true:
+
+- The field **must** be of type `string`
+- The field **must** be at the top-level of the request message (e.g. nested
+  fields are not supported)
+- The RPC **must** be a unary RPC (i.e. streaming RPCs are not supported)
+- The field **must not** be annotated
+  with [`google.api.field_behavior = REQUIRED`][required].
+- The field **must** be annotated
+  with [`google.api.field_info.format = UUID4`][uuid4].
+- The field name **must** be listed
+  in the [`google.api.MethodSettings.auto_populated_fields`][apf] of an entry
+  in [`google.api.Publishing.method_settings`][apf]
+  for the target method.
+
+**Note:** This feature currently only supports automatic population of string
+UUID4 values. It may be expanded in the future to support other format types.
+
+### Expected Generator and Client Library Behavior
+
+If the aforementioned requirements are met for a given field, client library
+generators **should**
+enable automatic population of said field in the generated client.
+If a field is specified in the `auto_populated_fields`, but does not meet the
+structural requirements, the client library generators **must not** enable
+automatic population for that field. Client library generators **may** emit an
+error during generation.
+
+Client libraries **must** reuse automatically populated values for retries of
+the same request i.e., the automatically populated
+fields **must not** be regenerated for each RPC attempt with a single request
+message.
+
+[AIP-155]: https://google.aip.dev/155
+
+[apf]: https://github.com/googleapis/googleapis/blob/master/google/api/client.proto
+
+[uuid4]: https://google.aip.dev/202#uuid4
+
+[required]: https://google.aip.dev/203#required