AIP-133: user-specified IDs rules conflict with "body" google.api.http option

[jonathaningram]

Consider the case where you want the user to provide a book ID in the book_id field (taken from https://google.aip.dev/133#user-specified-ids):

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-example.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;
}

Looking at this in the context of the RPC definition (from https://google.aip.dev/133):

rpc CreateBook(CreateBookRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books"
    body: "book"
  };
  option (google.api.method_signature) = "parent,book";
}

By asking for body: "book" it appears there is no way to provide the user-specified book_id in an HTTP JSON request because the entire JSON body is meant to contain the book details.

I believe in gRPC land this would be fine (because you can easily provide each of the required fields to the CreateBookRequest message), but for a HTTP-based API this doesn't work unless I'm missing something?

In my code I needed to make body: "*" so that I could allow users to pass the book ID. However this gives a lint error from the api-linter tool:

- file_path: file.proto
  problems:
  - message: The content of body "*" must map to the resource field "book" in the request message
    rule_id: core::0133::http-body
    rule_doc_uri: https://linter.aip.dev/133/http-body

I don't suppose the solution is to use body: "*" and then there needs to be a fix in api-linter to not warn about this if you're using user-specified IDs?

Thanks for taking the time to read my issue.

[mbleigh]

You can pass non-body fields as query parameters in the URL: POST /v1/books?bookId=my-book

…

On Wed, Jul 8, 2020, 11:51 PM Jonathan Ingram ***@***.***> wrote: Consider the case where you want the user to provide a book ID in the book_id field (taken from https://google.aip.dev/133#user-specified-ids): 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-example.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; } Looking at this in the context of the RPC definition (from https://google.aip.dev/133): rpc CreateBook(CreateBookRequest) returns (Book) { option (google.api.http) = { post: "/v1/{parent=publishers/*}/books" body: "book" }; option (google.api.method_signature) = "parent,book"; } By asking for body: "book" it appears there is no way to provide the user-specified book_id in an HTTP JSON request because the entire JSON body is meant to contain the book details. I believe in gRPC land this would be fine (because you can easily provide each of the required fields to the CreateBookRequest message), but for a HTTP-based API this doesn't work unless I'm missing something? In my code I needed to make body: "*" so that I could allow users to pass the book ID. However this gives a lint error from the api-linter tool: - file_path: file.proto problems: - message: The content of body "*" must map to the resource field "book" in the request message rule_id: core::0133::http-body rule_doc_uri: https://linter.aip.dev/133/http-body I don't suppose the solution is to use body: "*" and then there needs to be a fix in api-linter to not warn about this if you're using user-specified IDs? Thanks for taking the time to read my issue. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#542>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAAH7TKNJ3AT2JPFM2PUZ3R2VSIVANCNFSM4OVJB6PQ> .

[lukesneeringer]

What @mbleigh said. :)

[jonathaningram]

Thanks @mbleigh and @lukesneeringer it makes sense! It seems really obvious now...

For anyone else who arrives here, and you're using grpc-gateway it looks like the protoc-gen-swagger plugin may not be generating the query string params in the generated swagger.json files. I believe this is the relevant issue: grpc-ecosystem/grpc-gateway#559 I'm going to look into that.

For the record, grpc-gateway is correctly receiving and parsing a query string you provide so your server is fine. The lack of support in protoc-gen-swagger just means that your generated swagger.json is missing the param.