gRPC

This document introduces gRPC and provides usage instructions and guidelines. It also covers the protobuf concepts needed to use gRPC.

What Is gRPC?

gRPC is a remote procedure call (RPC) protocol created by Google. It lets you make network requests as though you were calling functions within your software. For details, see What is gRPC?.

Benefits of gRPC

Performance

Serializing and deserializing Protobuf for network requests is faster than doing so with JSON. gRPC network communication is also faster than HTTP POST/GET, with a particularly significant difference for POST requests. For details, see Mobile gRPC Benchmarks .

API-First Approach

Protobuf lets you define an API before developing its functionality. Defining the API first allows development teams to work in parallel, speeds up development, and makes the API more stable. For details, see Understanding the API-First Approach to Building Products.

REST API Support

An API defined in Protobuf can be exposed as a REST API through a gateway such as envoyproxy or grpc-gateway. Converting a gRPC API to OpenAPI makes the API-first approach available to clients that use REST APIs as well.

Using gRPC

Defining Data Structures and Services

gRPC uses protocol buffers by default to define data structures and services. For syntax and usage, see How to Define an API.

Generating gRPC Code

Use your .proto files to generate code for each programming language. Code-generation instructions are available for each language in gRPC Quick Start.

# Command example for generating code
protoc -I helloworld/ helloworld/helloworld.proto --go_out=plugins=grpc:helloworld

At Buzzvil, we build API libraries through the buzzapis repository. For details, see API Definition.

Implementing gRPC

Use the code generated from .proto files to implement the actual functionality. Generated code generally provides a server interface; implementing it makes the server’s functionality available to clients. See gRPC Quick Start for language-specific instructions.

Go Project Example

Generate authsvc.pb.go from authsvc.proto. Implement the generated service interface in server.go to expose the service to clients.

// authsvc.proto
service AuthService {
    rpc GetAuth(GetAuthRequest) returns (Auth);
}

// server.go
func (s *server) GetAuth(context.Context, *pb.GetAuthRequest) (*pb.Auth, error) {
    // ...
}

Python Project Example

Generate weathersvc_pb2.py and weathersvc_pb2_grpc.py from weathersvc.proto. Implement the generated service interface in server.py to expose the service to clients.

// weatersvc.proto
service WeatherService {
    rpc GetWeather (Location) returns (Weather) {}
}

# server.py
class WeatherServer(weathersvc_pb2_grpc.WeatherServiceServicer):
    def GetWeather(self, request, context):
        # ...

Running a gRPC Server

Create and run a gRPC server using the generated code. For details, see gRPC Tutorials. For language-specific instructions, see:

• Go Project
• Python Project

Making gRPC Client Requests

TBD

Generating OpenAPI Code

You can generate OpenAPI (Swagger) definitions from Protobuf files. Those definitions can in turn generate client code for REST APIs implemented with gRPC. See Usage 7.(Optional) Generate swagger definitions in grpc-gateway for generation instructions.

For the import "google/api/annotations.proto"; dependency, you can also follow Ensure HTTP rules are deployed in gRPC Transcoding when building.

protoc -I. \
  -I./googleapis \
  --swagger_out=logtostderr=true:. \
  path/to/your_service.proto