/* in transcoding from HTTP to gRPC

Question

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

message CreateBookRequest {
  // The publisher who will publish this book.
  // When using HTTP/JSON, this field is automatically populated based
  // on the URI, because of the `{parent=publishers/*}` syntax.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "library.googleapis.com/Book"
    }];

  Book book = 2 [(google.api.field_behavior) = REQUIRED];

  string book_id = 3;
}

I don't understand post: "/v1/{parent=publishers/*}/books"

I thought publishers was a field in CreateBookRequest, then it populates to http, so it is something like this post: "/v1/parent=publishers_field_value/books"

But publishers is not a field in CreateBookRequest

Answer 1

No, publishers is part of the expected value of the parent field. So suppose you have a protobuf request like this:

{
  "parent": "publishers/pub1",
  "book_id": "xyz"
  "book": {
    "author": "Stacy"
  }
}

That can be transcoded by a client into an HTTP request with:

• Method: POST
• URI: /v1/publishers/pub1/books?bookId=xyz (with the appropriate host name)
• Body:

  {
    "author": "Stacy"
  }
  

If you try to specify a request with a parent that doesn't match publishers/*, I'd expect transcoding to fail.

That's in terms of transcoding from protobuf to HTTP, in the request. (That's the direction I'm most familiar with, having been coding it in C# just this week...)

In the server, it should just be the opposite - so given the HTTP request above, the server should come up with the original protobuf request including parent="publishers/pub1".

For a lot more information on all of this, see the proto defining HttpRule.