aip-dev / google.aip.dev

API Improvement Proposals. https://aip.dev/
Other
1.08k stars 495 forks source link

A contradiction in the resource id usage #1382

Closed yufeng-deng closed 3 months ago

yufeng-deng commented 3 months ago

In the example provided in AIP133 and AIP155 there is

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 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 = 3 [(google.api.field_behavior) = REQUIRED];
}

Where book_id I believe is the resource_id. However in AIP122 there is a statement goes:

Resources may provide the resource ID as a separate field (e.g. book_id). This field must apply the OUTPUT_ONLY field behavior classification.

There is a REQUIRED annotation in the example, and to me it does not align with the OUTPUT_ONLY suggestion made above.

Could I ask how exactly resource ID is suggested to set? Should the client or the server generate resource ID?

yufeng-deng commented 3 months ago

It could be AIP122 is taking about the resource ID provided in the resource, but AIP133 and AIP155 are talking about the resource ID that is exposed to the createRequest together with the resource.