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

Author: alicejli

aip/client-libraries/4235.md

@@ -0,0 +1,55 @@
+---
+id: 4235
+state: approved
+created: 2024-03-07
+---
+
+# Automatically populate fields in the request message
+
+For APIs that leverage request idempotency as described via [AIP-155], APIs may
+choose 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. Nonetheless, this feature **must** 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, **all** 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
+- 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] entry
+  in [`google.api.Publishing.method_settings`][apf]
+  for the target method.
+
+### Expected Generator and Client Library Behavior
+
+If the aforementioned requirements are met for a given field, client library
+generators **must** 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