English | 中文

Introduction

The tRPC framework uses PB to define services, but it is still a common requirement to provide REST-style APIs based on the HTTP protocol. Unifying RPC and REST is not an easy task, and the tRPC-Go framework's HTTP RPC protocol aims to define the same set of PB files that can be called through RPC (through the client's NewXXXClientProxy provided by the stub code) or through native HTTP requests. However, such HTTP calls do not comply with the RESTful specification, for example, custom routes cannot be defined, wildcards are not supported, and the response body is empty when an error occurs (the error message can only be placed in the response header). Therefore, trpc additionally support the RESTful protocol and no longer attempt to force RPC and REST together. If the service is specified as RESTful protocol, it does not support the use of stub code calls and only supports HTTP client calls. However, the benefit of this approach is that it can provide APIs that comply with RESTful specification through the protobuf annotation in the same set of PB files and can use various tRPC framework plugins or filters.

Principles

Transcoder

Unlike other protocol plugins in the tRPC-Go framework, the RESTful protocol plugin implements a tRPC and HTTP/JSON transcoder based on the tRPC HttpRule at the Transport layer. This eliminates the need for Codec encoding and decoding processes as PB is directly obtained after transcoding and processed in the REST Stub generated by the trpc tool.

Transcoder Core: HttpRule

For a service defined using the same set of PB files, support for both RPC and REST calls requires a set of rules to indicate the mapping between RPC and REST, or more precisely, the transcoding between PB and HTTP/JSON. In the industry, Google has defined such rules, namely HttpRule, which tRPC's implementation also references. tRPC's HttpRule needs to be specified in the PB file as an option: option (trpc.api.http), which means that the same set of PB-defined services support both RPC and REST calls. Now, let's take an example of how to bind HttpRule to the SayHello method in a Greeter service:

service Greeter {
  rpc SayHello(HelloRequest) returns (HelloReply) {
    option (trpc.api.http) = {
      post: "/v1/foobar/{name}"
      body: "*"
      additional_bindings: {
        post: "/v1/foo/{name=/x/y/**}"
        body: "single_nested"
        response_body: "message"
      }
    };
  }
}
message HelloRequest {
  string name = 1;
  Nested single_nested = 2;
  oneof oneof_value {
    google.protobuf.Empty oneof_empty = 3;
    string oneof_string = 4;
  }
}
message Nested {
  string name = 1;
}
message HelloReply {
  string message = 1;
}

Through the above example, it can be seen that HttpRule has the following fields:

The "body" field indicates which field of the PB request message is carried in the HTTP request body.

The "response_body" field indicates which field of the PB response message is carried in the HTTP response body.

The "additional_bindings" field represents additional HttpRule, meaning that an RPC method can be bound to multiple HttpRules.

Combining the specific rules of HttpRule, let's take a look at how the HTTP request/response are mapped to HelloRequest and HelloReply in the above example:

When mapping, the "leaf fields" of the RPC request Proto Message (which refers to the fields that cannot be nested and traversed further, in the above example HelloRequest.Name is a leaf field, while HelloRequest.SingleNested is not, and only HelloRequest.SingleNested.Name is) are mapped in three ways:

The leaf fields are referenced by the URL Path of the HttpRule: If the URL Path of the HttpRule references one or more fields in the RPC request message, then these fields are passed through the HTTP request URL Path. However, these fields must be non-array fields of native basic types, and do not support fields of message types or array fields. In the above example, if the HttpRule selector field is defined as post: "/v1/foobar/{name}", then the value of the HelloRequest.Name field is mapped to "xyz" when the HTTP request POST /v1/foobar/xyz is made.

The leaf fields are referenced by the Body of the HttpRule: If the field to be mapped is specified in the Body of the HttpRule, then this field in the RPC request message is passed through the HTTP request Body. In the above example, if the HttpRule body field is defined as body: "name", then the value of the HelloRequest.Name field is mapped to "xyz" when the HTTP request Body is "xyz".

Other leaf fields: Other leaf fields are automatically turned into URL query parameters, and if they are repeated fields, multiple queries of the same URL query parameter are supported. In the above example, if the selector in the additional_bindings specifies post: "/v1/foo/{name=/x/y/*}", and the body is not specified as body: "", then all fields in HelloRequest except HelloRequest.Name are passed through URL query parameters. For example, if the HTTP request POST /v1/foo/x/y/z/xyz?single_nested.name=abc is made, the value of the HelloRequest.Name field is mapped to "/x/y/z/xyz", and the value of the HelloRequest.SingleNested.Name field is mapped to "abc".

Supplement:

If the field is not specified in the Body of the HttpRule and is defined as "", then each field of the request message that is not bound by the URL path is passed through the Body of the HTTP request. That is, the URL query parameters are invalid.

If the Body of the HttpRule is empty, then every field of the request message that is not bound by the URL path becomes a URL query parameter. That is, the Body is invalid.

If the response_body of the HttpRule is empty, then the entire PB response message will be serialized into the HTTP response Body. In the above example, if response_body is "", then the serialized HelloReply is the HTTP response Body.

HttpRule body and response_body fields can reference fields of the PB Message, which may or may not be leaf fields, but must be first-level fields in the PB Message. For example, for HelloRequest, HttpRule body can be defined as "name" or "single_nested", but not as "single_nested.name".

Now let's take a look at a few more examples to better understand how to use HttpRule.

1. Take the content that matches "messages/*" inside the URL Path as the value of the "name" field:

service Messaging {
  rpc GetMessage(GetMessageRequest) returns (Message) {
    option (trpc.api.http) = {
        get: "/v1/{name=messages/*}"
    };
  }
}
message GetMessageRequest {
  string name = 1; // Mapped to URL path.
}
message Message {
  string text = 1; // The resource content.
}