HTTP EP description

You need to describe HTTP endpoints and parameters to expose your gRPC API methods over HTTP. There's two ways to do it:

• Inline description in .proto
  • + Easier to generate and use
  • - Client generators need to be able to import google/api/annotations.proto (here) to generate anything
• Separate YAML
  • + Proto's API description is cleaner
  • + Clients don't need to import any external dependencies for generation
  • + All HTTP paths for many services can be described in one file
  • - Server generation command is longer/less flexible
  • - It's harder to keep proto and HTTP definitions in sync

See official doc for more details.

Inline description

You need to import google/api/annotations.proto and describe your endpoints using google.api.http option:

syntax = "proto3";
package foopkg;

import "google/api/annotations.proto";

service SampleService {
  rpc Foo(FooRequest) returns (FooResponse) {
    option (google.api.http) = {
      get: "/v1/sample/foo/{a}/{bar.b}" // GET request with variables A and Bar.B in the query path
    };
  }
  rpc Bar(BarRequest) returns (BarResponse) {
    option (google.api.http) = {
      post: "/v1/sample/bar" // POST request with request in the body
      body: "*"
    };
  }
}

Use the protoc output --goclay_out=:. to generate the file.

YAML description

You need to describe the bare-bones API to your protofile:

syntax = "proto3";
package foopkg;

service SampleService {
  rpc Foo(FooRequest) returns (FooResponse) {
  }
  rpc Bar(BarRequest) returns (BarResponse) {
  }
}

Describe HTTP EP in YAML:

type: google.api.Service
config_version: 3

http:
  rules:
  - selector: foopkg.SampleService.Foo
    get: '/v1/sample/foo/{a}/{bar.b}'
  - selector: foopkg.SampleService.Bar
    post: '/v1/sample/bar'
    body: '*'

Use the protoc output --goclay_out=grpc_api_configuration=path/to/yaml:. to generate the file.