feat(AIP-133) up resource_id guidance to should (#1019)

* feat(AIP-133) up resource_id guidance to should

The current wording implies that user-settable resource_ids
are somewhat helpful *may*, when in most cases they are very
beneficial: they are critical for declarative clients to uniquely
identify resources and prevent duplicates, and enable the user
to provide semantic names and organization for resources.

Generally the guidance would be better for APIs if they were
added if at all possible, and only skipped if there the usage
pattern is exceptional (e.g. job resources with significant churn,
revisions where a unique identifier is determined by the custom
method).

* addressing feedback

- make user-settable IDs a must.
- add rationale

* address feedback

- removed must on resource_id in AIP-128

* more wording tweaks

- clarifying and fixing user-settable ID section.

* addressing feedback

user-settable -> client-settable.

Adding more rationale, fixing ordering so ID is required first,
then the body of the resource.

Author: toumorokoshi

aip/general/0128.md

@@ -101,11 +101,15 @@ A significant amount of guidance is more strict for declarative-friendly
 interfaces, due to the focus on automation on top of these resources. This list
 is a comprehensive reference to declarative-friendly guidance in other AIPs:
 
-- Resources **must** use user-settable resource IDs: see AIP-133.
 - Resources **should not** employ custom methods: see AIP-136.
 - Resources **must** use the `Update` method for repeated fields: see AIP-144.
 - Resources **must** include certain standard fields: see AIP-148.
 - Resources **must** have an `etag` field: see AIP-154.
 - Resources **should** provide change validation: see AIP-163.
 - Resources **should not** implement soft-delete. If the id cannot be re-used,
-  the resource **must** implement soft-delete and the undelete RPC: see AIP-164
+  the resource **must** implement soft-delete and the undelete RPC: see AIP-164
+
+## Changelog
+
+- **2023-05-11**: removed must on resource_id, which was upstreamd to a general
+  must

aip/general/0133.md

@@ -58,10 +58,8 @@ rpc CreateBook(CreateBookRequest) returns (Book) {
   **must** map to the resource field in the request message.
   - All remaining fields **should** map to URI query parameters.
 - There **should** be exactly one `google.api.method_signature` annotation,
-  with a value of `"parent,{resource}"` if the resource being created is not a
-  top-level resource, or with a value of `"{resource}"` if the resource being
-  created is a top-level resource (unless the method supports [user-specified
-  IDs](#user-specified-ids)).
+  with a value of `"parent,{resource},{resource}_id"`, or "`"parent,{resource}"`
+  if the resource ID is not required.
 
 ### Request message
 
@@ -77,8 +75,15 @@ message CreateBookRequest {
       child_type: "library.googleapis.com/Book"
     }];
 
+  // The ID to use for the book, which will become the final component of
+  // the book's resource name.
+  //
+  // This value should be 4-63 characters, and valid characters
+  // are /[a-z][0-9]-/.
+  string book_id = 2 [(google.api.field_behavior) = REQUIRED];
+
   // The book to create.
-  Book book = 2 [(google.api.field_behavior) = REQUIRED];
+  Book book = 3 [(google.api.field_behavior) = REQUIRED];
 }
 ```
 
@@ -87,6 +92,7 @@ message CreateBookRequest {
   - The field **should** be [annotated as required][aip-203].
   - The field **must** identify the [resource type][aip-123] of the resource
     being created.
+- A `{resource}_id` field **must** be included.
 - The resource field **must** be included and **must** map to the POST body.
 - The request message **must not** contain any other required fields and
   **should not** contain other optional fields except those described in this
@@ -120,9 +126,10 @@ to done if the request is effectively immediate.
 
 ### User-specified IDs
 
-Sometimes, an API needs to allow a client to specify the ID component of a
-resource (the last segment of the resource name) on creation. This is common if
-users are allowed to choose that portion of their resource names.
+An API **must** allow a client to specify the ID component
+of a resource (the last segment of the resource name) on creation. An API
+**may** allow the `{resource}_id` field have the [field_behavior][] `OPTIONAL`,
+and generate a system-generated ID if one is not specified.
 
 For example:
 
@@ -134,31 +141,6 @@ publishers/lacroix/books/les-miserables
 publishers/012345678-abcd-cdef/books/12341234-5678-abcd
 ```
 
-Create RPCs **may** support this behavior by providing a `string {resource}_id`
-field on the request message:
-
-```proto
-message CreateBookRequest {
-  // The parent resource where this book will be created.
-  // Format: publishers/{publisher}
-  string parent = 1 [
-    (google.api.field_behavior) = REQUIRED,
-    (google.api.resource_reference) = {
-      child_type: "library.googleapis.com/Book"
-    }];
-
-  // The book to create.
-  Book book = 2 [(google.api.field_behavior) = REQUIRED];
-
-  // The ID to use for the book, which will become the final component of
-  // the book's resource name.
-  //
-  // This value should be 4-63 characters, and valid characters
-  // are /[a-z][0-9]-/.
-  string book_id = 3;
-}
-```
-
 - The `{resource}_id` field **must** exist on the request message, not the
   resource itself.
   - The field **may** be required or optional. If it is required, it **should**
@@ -181,9 +163,6 @@ message CreateBookRequest {
 **Note:** For REST APIs, the user-specified ID field, `{resource}_id`,
 is provided as a query parameters on the request URI.
 
-**Important:** Declarative-friendly resources (AIP-128) **must** support
-user-specified IDs.
-
 ### Errors
 
 See [errors][], in particular [when to use PERMISSION_DENIED and
@@ -194,17 +173,34 @@ NOT_FOUND errors][permission-denied].
 - For ensuring idempotency in `Create` methods, see [AIP-155][].
 - For naming resources involving Unicode, see [AIP-210][].
 
+## Rationale
+
+### Requiring client-settable ids
+
+[IaC][] clients use the resource ID as a way to identify a resource for applying
+updates and for conflict resolution. The lack of a client-settable ID means a
+client is unable to find the resource unless they store the identifier locally,
+and can result in re-creating the resource. This in turn has a downstream effect
+on all resources that reference it, forcing them to update to the the ID of the
+newly-created resource.
+
+Having a client-settable ID also means the client can precalculate the resource
+name and use it in references from other resources.
+
 [aip-121]: ./0121.md
 [aip-122]: ./0122.md
 [aip-123]: ./0123.md
 [aip-155]: ./0155.md
 [aip-203]: ./0203.md
 [aip-210]: ./0210.md
 [errors]: ./0193.md
+[field_behavior]: ./203.md
+[IaC]: ./0009.md#iac
 [permission-denied]: ./0193.md#permission-denied
 
 ## Changelog
 
+- **2023-05-11**: Changing guidance around resource_id to a must.
 - **2022-11-04**: Referencing aggregated error guidance in AIP-193, similar to other CRUDL AIPs.
 - **2022-06-02**: Changed suffix descriptions to eliminate superfluous "-".
 - **2020-10-06**: Added declarative-friendly guidance.