Defining Empty Requests and Responses in gRPC: Best Practices and Implementation

In gRPC service design, developers often encounter situations where they need to define RPC methods without parameters or return values. For example, user logout operations may not require any input parameters nor return specific data; system status queries may only need to return status information without input parameters; log recording may only need to receive log data without returning results. These scenarios raise an important question: how to elegantly handle empty requests and responses in proto3 syntax?

Limitations of proto3 Syntax and Solutions

The proto3 syntax itself does not directly support completely omitting request or response types in RPC definitions. In proto files, each rpc method must explicitly specify request message types and response message types, even if these messages may not contain any fields. This means syntax like rpc Logout; is not allowed in proto3.

Facing this limitation, developers typically have two choices: create custom empty message types, or use the predefined Empty type provided by Google. The first approach is shown in the example:

message Null {};

rpc Logout (Null) returns (Null);
rpc Status (Null) returns (Status);
rpc Log (LogData) returns (Null);

While this method works, it suffers from code duplication and maintenance issues. When multiple services require empty message types, each service may define its own empty messages, leading to API inconsistency and redundancy.

Official Recommended Best Practices

The Google Protocol Buffers team has anticipated this need and provided the google.protobuf.Empty type in the standard library. This predefined empty message type is located in the empty.proto file, with a very simple definition:

message Empty {}

The benefits of using the predefined Empty type are multifaceted. First, it ensures API consistency—all scenarios using empty messages reference the same type. Second, it reduces code duplication—developers don't need to repeatedly define the same empty message in each service. Most importantly, it follows the important principle proposed by Kenton Varda: "We as developers are really bad at guessing what we might want in the future. So I recommend being safe by always defining custom params and results types for every method, even if they are empty."

Practical Application Examples

In actual gRPC service definitions, examples using the predefined Empty type are as follows:

import "google/protobuf/empty.proto";
package MyPackage;

service MyService {
  rpc Check(google.protobuf.Empty) returns (google.protobuf.Empty) {}
  rpc GetStatus(google.protobuf.Empty) returns (StatusResponse) {}
  rpc WriteLog(LogRequest) returns (google.protobuf.Empty) {}
}

This design pattern not only complies with proto3 syntax requirements but also preserves flexibility for future API extensions. If parameters need to be added to the Check method in the future, only the request message type needs to be modified without changing the method signature.

Design Considerations and Extensibility

Using predefined empty message types instead of omitting parameters reflects good API design principles. Even if a method currently doesn't need parameters or return values, defining explicit message types for it lays the foundation for future feature expansion. When business requirements change, developers can add fields to existing message types without breaking existing client compatibility.

Furthermore, this design improves code readability and maintainability. By examining proto files, developers can clearly understand the input-output contract of each RPC method, even if some messages are currently empty. Explicit type declarations also help generate more accurate documentation and client code.

Implementation Details and Considerations

When using the predefined Empty type, correct import statements must be noted. The Empty type is defined in the google/protobuf/empty.proto file and needs to be imported via import statements at the beginning of proto files. Generated code in different programming languages may represent the Empty type differently, but the core concept remains the same: a message containing no fields.

In server-side implementations, methods handling Empty parameters are usually simple. For example, in Go, an RPC method handling empty requests might look like this:

func (s *MyServer) Check(ctx context.Context, req *emptypb.Empty) (*emptypb.Empty, error) {
    // Execute check logic
    return &emptypb.Empty{}, nil
}

When making client calls, Empty instances also need to be created as parameters:

emptyReq := &emptypb.Empty{}
resp, err := client.Check(ctx, emptyReq)

Although this code may seem somewhat redundant, this explicit design ensures type safety and API consistency.

Conclusion

When handling empty requests and responses in gRPC service design, it is recommended to use the predefined google.protobuf.Empty type rather than creating custom empty message types or attempting to use unsupported syntax. This method not only complies with proto3 syntax specifications but also follows good API design principles, preserving flexibility for future feature expansion while ensuring code consistency and maintainability. By adopting this best practice, developers can build more robust and extensible gRPC services.