AWS re:Invent happy hour: Dec 1, 6 PM PST at MGM Grand RSVP

Getting Started with gRPC: A Developer's Guide


gRPC (gRPC Remote Procedure Calls) is a modern, open-source, high-performance RPC framework that can run in any environment. Originally developed by Google, gRPC uses HTTP/2 for transport, Protocol Buffers as the interface description language, and provides features such as authentication, bidirectional streaming, flow control, blocking or nonblocking bindings, and cancellation and timeouts.

What is gRPC?

gRPC is a framework that enables efficient communication between distributed systems. Unlike traditional REST APIs that use JSON over HTTP/1.1, gRPC uses Protocol Buffers (protobuf) for serialization and HTTP/2 for transport, resulting in faster, more efficient communication.

Key Benefits of gRPC

1. Performance

  • Binary Protocol: Protocol Buffers are more compact than JSON
  • HTTP/2: Multiplexing, server push, and header compression
  • Code Generation: Strongly-typed client and server code

2. Language Agnostic

gRPC supports multiple programming languages including:

  • Go
  • Java
  • Python
  • JavaScript/TypeScript
  • C++
  • C#
  • Ruby

3. Streaming Support

  • Unary RPCs: Simple request-response
  • Server streaming: Server sends multiple responses
  • Client streaming: Client sends multiple requests
  • Bidirectional streaming: Both sides send sequences of messages

Setting Up Your First gRPC Service

Step 1: Define Your Service

Create a .proto file to define your service interface:

syntax = "proto3";

package helloworld;

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

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

Step 2: Generate Code

Use the Protocol Buffer compiler to generate client and server code:

protoc --go_out=. --go_opt=paths=source_relative \
    --go-grpc_out=. --go-grpc_opt=paths=source_relative \
    helloworld.proto

Step 3: Implement the Server

package main

import (
    "context"
    "fmt"
    "log"
    "net"

    "google.golang.org/grpc"
    pb "your-module/helloworld"
)

type server struct {
    pb.UnimplementedGreeterServer
}

func (s *server) SayHello(ctx context.Context, in *pb.HelloRequest) (*pb.HelloReply, error) {
    return &pb.HelloReply{Message: "Hello " + in.GetName()}, nil
}

func main() {
    lis, err := net.Listen("tcp", ":50051")
    if err != nil {
        log.Fatalf("failed to listen: %v", err)
    }
    
    s := grpc.NewServer()
    pb.RegisterGreeterServer(s, &server{})
    
    if err := s.Serve(lis); err != nil {
        log.Fatalf("failed to serve: %v", err)
    }
}
LLM prompt for this step
Create a compilable Greeter proto and Go module with the correct go_package, generate Go message and service stubs with compatible protoc plugins, implement SayHello, and verify it using a local client.

Testing gRPC Services with Proxymock

One of the challenges with gRPC development is testing with realistic data. Proxymock can help by capturing real gRPC traffic and creating mocks:

Recording gRPC Traffic

# Record gRPC traffic
proxymock record --port 50051 --out ./grpc-mocks

# Your gRPC traffic gets captured automatically

Mocking gRPC Services

# Start mock server with recorded traffic
proxymock mock --in ./grpc-mocks --port 50052

# Your tests now use realistic production data
LLM prompt for this step
Check the installed proxymock record and mock help for gRPC listener and mapping options. Adapt the article's historical port examples to record my local Greeter service and serve the resulting recording on a separate listener with passthrough disabled. Verify the client receives the expected gRPC response.

Best Practices

1. Design Your APIs Carefully

  • Use descriptive field names
  • Version your APIs properly
  • Consider backward compatibility

2. Error Handling

import "google.golang.org/grpc/codes"
import "google.golang.org/grpc/status"

func (s *server) SayHello(ctx context.Context, in *pb.HelloRequest) (*pb.HelloReply, error) {
    if in.GetName() == "" {
        return nil, status.Errorf(codes.InvalidArgument, "name cannot be empty")
    }
    return &pb.HelloReply{Message: "Hello " + in.GetName()}, nil
}

3. Use Interceptors

Implement cross-cutting concerns like logging, authentication, and metrics:

func loggingInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
    start := time.Now()
    resp, err := handler(ctx, req)
    log.Printf("Method: %s, Duration: %s, Error: %v", info.FullMethod, time.Since(start), err)
    return resp, err
}
LLM prompt for this step
Add explicit gRPC status errors for invalid Greeter input and a unary logging interceptor that preserves context and returned errors. Test the gRPC status code as well as the response message.

Run this workflow with an LLM

Give this prompt to a coding assistant with access to your project and this article. Supply environment-specific values it cannot discover.

Whole-workflow LLM prompt
Read https://speedscale.com/blog/getting-started-with-grpc-a-developers-guide/ and inspect my project instructions first. Build a minimal Go Greeter gRPC service and client from a proto3 contract, generate compatible stubs, and verify a successful call and a meaningful gRPC error. Record and mock a local exchange only after checking the installed proxymock gRPC options; keep real and mock listener ports distinct. Check installed tool help before adapting commands. Report the checks actually run, their results, and anything you could not verify.

Conclusion

gRPC provides a powerful framework for building efficient, scalable microservices. With its strong typing, excellent performance, and multi-language support, it’s an excellent choice for modern distributed systems.

When combined with tools like Proxymock for testing and development, you can build robust gRPC services with confidence, knowing your tests use real production data patterns.

Next Steps

  • Explore advanced gRPC features like streaming
  • Implement authentication and security
  • Set up load balancing and service discovery
  • Consider using Proxymock for comprehensive gRPC testing

For more information on testing gRPC services with realistic data, check out our Proxymock documentation.

Stop writing API mocks by hand

proxymock records real traffic from your running app and replays it as mocks for HTTP, gRPC, Postgres, Kafka, and more. Install locally, activate once, and start recording.