Developer Guides
gRPC APIs

gRPC APIs

gRPC (grpc.io) is a high performance, language-agnostic RPC framework.
It is widely used in microservices architectures, to connect services in and across data centers, as well as in last mile communications to devices, mobile apps and browsers applications.

gRPC is built on the HTTP/2 standard and uses Protocol Buffers (Protobuf) as its interface definition language (IDL) to define service methods and message types.

Why gRPC

gRPC provides several key benefits that make it a powerful choice for building modern distributed systems:

  1. Support for multiple programming language gRPC supports multiple programming languages, including but not limited to C++, Java, Python, Go, Ruby, and more. This allows teams to build services in different languages and have them communicate seamlessly.

  2. Strongly-Typed Contracts gRPC uses Protocol Buffers to define service methods and messages. This enforces a strongly-typed contract between services, reducing the chances of errors caused by mismatched data types or structures.

  3. Efficient Communication Built on HTTP/2, gRPC supports multiplexed streams, which means multiple requests can be sent and received concurrently on the same connection. This reduces latency and improves overall efficiency of the service-to-service communication.

  4. Bidirectional Streaming gRPC supports different types of streaming: Unary (single request/response), Server streaming (single request, multiple responses), Client streaming (multiple requests, single response), and Bidirectional streaming (multiple requests/responses). This flexibility allows for more complex communication patterns, such as real-time data streaming.

  5. Built-in Authentication and Security gRPC provides built-in support for authentication mechanisms such as SSL/TLS and OAuth, ensuring secure communication between services. This is especially critical in environments where sensitive data is transmitted.

Use Cases

gRPC is versatile and can be used in various scenarios, including:

  • Microservices Communication: gRPC is ideal for communication between microservices due to its efficiency and language-agnostic nature.

  • Real-Time Data Streaming: With support for bidirectional streaming, gRPC can handle real-time data flows, such as live updates or sensor data transmission.

  • Mobile Backend Services: gRPC’s compact and efficient binary format makes it suitable for mobile devices with limited bandwidth.

How gRPC Works

Service Definition

A gRPC service is defined using Protocol Buffers. The service definition includes the RPC (Remote Procedure Call) methods that can be invoked, along with the message types used for requests and responses.

greeter.proto
syntax = "proto3"

service Greeter {
    rpc SayHello (HelloRequest) returns (HelloReply) {}
}

message HelloRequest {
    string name = 1;
}

message HelloReply {
    string message = 1;
}

Code Generation

Once the service is defined, the Protocol Buffers compiler (protoc) generates code in the target language(s). For example, if you’re working in Python, you can generate the client code using the following command:

protoc --python_out=. --grpc_python_out=. greeter.proto

This command generates two files:

  • greeter_pb2.py: Contains the data structures for the request and response messages.
  • greeter_pb2_grpc.py: Contains the client classes.

Using the Python Client Library

After generating the client code, you can use it to interact with the gRPC service. Below is an example of how to use the generated client library in Python to invoke the SayHello() method on a remote server:

client.py
import grpc
import greeter_pb2
import greeter_pb2_grpc

def run():
    # Create a channel to connect to the server
    with grpc.insecure_channel('localhost:50051') as channel:
        # Create a stub (client)
        stub = greeter_pb2_grpc.GreeterStub(channel)
        
        # Create a request object
        request = greeter_pb2.HelloRequest(name='World')
        
        # Call the SayHello method and get the response
        response = stub.SayHello(request)
        
        print("Greeter client received: " + response.message)

if __name__ == '__main__':
    run()

In this example:

  • A gRPC channel is created to connect to the server running on localhost at port 50051.
  • A stub (client) is created from the GreeterStub class generated by protoc.
  • The client creates a HelloRequest message and calls the SayHello() method on the stub, sending the request to the server.
  • The server processes the request and sends back a HelloReply message, which the client prints out.

Learn more

Protobuf data-structures