Getting Started With gRPC in Golang

Hi there! I'm Shrijith Venkatrama, founder of Hexmos. Right now, I’m building LiveAPI, a tool that makes generating API docs from your code ridiculously easy. gRPC is a framework for building fast, scalable APIs, especially in distributed systems like microservices. It’s built on HTTP/2 and Protocol Buffers (protobuf), offering a different approach from REST. If you’re working in Golang and need efficient communication between services, gRPC is worth a look. This post walks you through what it does, how to set up a basic example, and a more advanced duplex streaming case to show its real power. What gRPC Brings to the Table gRPC tackles some common pain points in API design: Speed: It uses HTTP/2 to handle multiple requests over one connection and protobuf for compact binary data, cutting down on latency and payload size compared to REST’s JSON over HTTP/1.1. Cross-Language Support: It generates client and server code for many languages, so a Go service can talk to a Python one without extra effort. Streaming: Unlike REST’s request-response model, gRPC supports bidirectional streaming for real-time data. Strong Typing: Protobuf defines your API contract, reducing runtime errors with generated, typed code. Scalability: Built-in load balancing and service discovery make it a fit for large systems. It’s not a REST replacement—REST is simpler for public, browser-friendly APIs. But for internal services or performance-critical apps, gRPC has an edge. Setting Up gRPC in Go: Basic Hello World Let’s build a simple gRPC service where a client sends a name, and the server replies with a greeting. Here’s every step from scratch. Step 1: Initialize the Project Create a new directory and set up a Go module: mkdir grpc-hello cd grpc-hello go mod init grpc-hello Step 2: Install Dependencies You’ll need the gRPC library, protobuf tools, and the Go code generator: go get google.golang.org/grpc go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest go install google.golang.org/protobuf/cmd/protoc-gen-go@latest Install the protoc compiler manually from here and add it to your PATH. Step 3: Define the Service Create a proto/ directory and add proto/hello.proto: syntax = "proto3"; package proto; option go_package = "./proto"; service Greeter { rpc SayHello (HelloRequest) returns (HelloResponse); } message HelloRequest { string name = 1; } message HelloResponse { string message = 1; } This defines a Greeter service with one method, SayHello. Step 4: Generate Code Compile the .proto file into Go: protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=paths=source_relative proto/hello.proto This creates proto/hello.pb.go and proto/hello_grpc.pb.go. Step 5: Write the Server Create server/main.go: package main import ( "context" "fmt" "log" "net" pb "grpc-hello/proto" "google.golang.org/grpc" ) type server struct { pb.UnimplementedGreeterServer } func (s server) SayHello(ctx context.Context, req pb.HelloRequest) (*pb.HelloResponse, error) { return &pb.HelloResponse{Message: fmt.Sprintf("Hello, %s!", req.Name)}, 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{}) log.Println("Server running on :50051") if err := s.Serve(lis); err != nil { log.Fatalf("failed to serve: %v", err) } } Step 6: Write the Client Create client/main.go: package main import ( "context" "log" pb "grpc-hello/proto" "google.golang.org/grpc" ) func main() { conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure()) if err != nil { log.Fatalf("did not connect: %v", err) } defer conn.Close() c := pb.NewGreeterClient(conn) resp, err := c.SayHello(context.Background(), &pb.HelloRequest{Name: "Alice"}) if err != nil { log.Fatalf("could not greet: %v", err) } log.Printf("Response: %s", resp.Message) } Step 7: Test It Run the server in one terminal: go run server/main.go Then the client in another: go run client/main.go You’ll see "Response: Hello, Alice!" in the client’s output. That’s the basics working. How gRPC Compares to REST gRPC’s efficiency comes from HTTP/2 and protobuf. Here’s a quick comparison: Feature REST (JSON) gRPC (Protobuf) Payload Size Larger (text-based) Smaller (binary) Latency Higher (HTTP/1.1) Lower (HTTP/2) Streaming Limited Bidirectional Typing Manual Auto-generated See benchmark for numbers on performance - but suffice to say here - generally as the traffic grows - gRPC scales more efficiently and gracefully. Going Deeper: Duplex Streaming Example The basic example is fine, but gRPC’s

Apr 3, 2025 - 19:32

Hi there! I'm Shrijith Venkatrama, founder of Hexmos. Right now, I’m building LiveAPI, a tool that makes generating API docs from your code ridiculously easy.

gRPC is a framework for building fast, scalable APIs, especially in distributed systems like microservices.

It’s built on HTTP/2 and Protocol Buffers (protobuf), offering a different approach from REST.

If you’re working in Golang and need efficient communication between services, gRPC is worth a look.

This post walks you through what it does, how to set up a basic example, and a more advanced duplex streaming case to show its real power.

What gRPC Brings to the Table

gRPC tackles some common pain points in API design:

Speed: It uses HTTP/2 to handle multiple requests over one connection and protobuf for compact binary data, cutting down on latency and payload size compared to REST’s JSON over HTTP/1.1.
Cross-Language Support: It generates client and server code for many languages, so a Go service can talk to a Python one without extra effort.
Streaming: Unlike REST’s request-response model, gRPC supports bidirectional streaming for real-time data.
Strong Typing: Protobuf defines your API contract, reducing runtime errors with generated, typed code.
Scalability: Built-in load balancing and service discovery make it a fit for large systems.

It’s not a REST replacement—REST is simpler for public, browser-friendly APIs. But for internal services or performance-critical apps, gRPC has an edge.

Setting Up gRPC in Go: Basic Hello World

Let’s build a simple gRPC service where a client sends a name, and the server replies with a greeting. Here’s every step from scratch.

Step 1: Initialize the Project

Create a new directory and set up a Go module:

mkdir grpc-hello
cd grpc-hello
go mod init grpc-hello

Step 2: Install Dependencies

You’ll need the gRPC library, protobuf tools, and the Go code generator:

go get google.golang.org/grpc
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest

Install the protoc compiler manually from here and add it to your PATH.

Step 3: Define the Service

Create a proto/ directory and add proto/hello.proto:

syntax = "proto3";
package proto;
option go_package = "./proto";

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloResponse);
}

message HelloRequest {
  string name = 1;
}

message HelloResponse {
  string message = 1;
}

This defines a Greeter service with one method, SayHello.

Step 4: Generate Code

Compile the .proto file into Go:

protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=paths=source_relative proto/hello.proto

This creates proto/hello.pb.go and proto/hello_grpc.pb.go.

Step 5: Write the Server

Create server/main.go:

package main

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

    pb "grpc-hello/proto"
    "google.golang.org/grpc"
)

type server struct {
    pb.UnimplementedGreeterServer
}

func (s *server) SayHello(ctx context.Context, req *pb.HelloRequest) (*pb.HelloResponse, error) {
    return &pb.HelloResponse{Message: fmt.Sprintf("Hello, %s!", req.Name)}, 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{})
    log.Println("Server running on :50051")
    if err := s.Serve(lis); err != nil {
        log.Fatalf("failed to serve: %v", err)
    }
}

Step 6: Write the Client

Create client/main.go:

package main

import (
    "context"
    "log"

    pb "grpc-hello/proto"
    "google.golang.org/grpc"
)

func main() {
    conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure())
    if err != nil {
        log.Fatalf("did not connect: %v", err)
    }
    defer conn.Close()

    c := pb.NewGreeterClient(conn)
    resp, err := c.SayHello(context.Background(), &pb.HelloRequest{Name: "Alice"})
    if err != nil {
        log.Fatalf("could not greet: %v", err)
    }
    log.Printf("Response: %s", resp.Message)
}

Step 7: Test It

Run the server in one terminal:

go run server/main.go

Then the client in another:

go run client/main.go

You’ll see "Response: Hello, Alice!" in the client’s output. That’s the basics working.

How gRPC Compares to REST

gRPC’s efficiency comes from HTTP/2 and protobuf. Here’s a quick comparison:

Feature	REST (JSON)	gRPC (Protobuf)
Payload Size	Larger (text-based)	Smaller (binary)
Latency	Higher (HTTP/1.1)	Lower (HTTP/2)
Streaming	Limited	Bidirectional
Typing	Manual	Auto-generated

See benchmark for numbers on performance - but suffice to say here - generally as the traffic grows - gRPC scales more efficiently and gracefully.

Going Deeper: Duplex Streaming Example

The basic example is fine, but gRPC’s real strength is streaming. Let’s build a chat-like service with bidirectional streaming, where the client and server send messages back and forth.

Step 1: Update the Proto File

Edit proto/hello.proto:

syntax = "proto3";
package proto;
option go_package = "./proto";

service Chat {
  rpc ChatStream (stream ChatMessage) returns (stream ChatMessage);
}

message ChatMessage {
  string user = 1;
  string text = 2;
}

Regenerate the code:

protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=paths=source_relative proto/hello.proto

Step 2: Write the Streaming Server

Update server/main.go:

package main

import (
    "io"
    "log"
    "net"

    pb "grpc-hello/proto"
    "google.golang.org/grpc"
)

type server struct {
    pb.UnimplementedChatServer
}

func (s *server) ChatStream(stream pb.Chat_ChatStreamServer) error {
    for {
        msg, err := stream.Recv()
        if err == io.EOF {
            return nil // Client closed the stream
        }
        if err != nil {
            return err
        }
        log.Printf("Received from %s: %s", msg.User, msg.Text)
        // Echo back with a server twist
        err = stream.Send(&pb.ChatMessage{
            User: "Server",
            Text: "Echo: " + msg.Text,
        })
        if err != nil {
            return err
        }
    }
}

func main() {
    lis, err := net.Listen("tcp", ":50051")
    if err != nil {
        log.Fatalf("failed to listen: %v", err)
    }
    s := grpc.NewServer()
    pb.RegisterChatServer(s, &server{})
    log.Println("Server running on :50051")
    if err := s.Serve(lis); err != nil {
        log.Fatalf("failed to serve: %v", err)
    }
}

Step 3: Write the Streaming Client

Update client/main.go:

package main

import (
    "context"
    "io"
    "log"
    "time"

    pb "grpc-hello/proto"
    "google.golang.org/grpc"
)

func main() {
    conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure())
    if err != nil {
        log.Fatalf("did not connect: %v", err)
    }
    defer conn.Close()

    c := pb.NewChatClient(conn)
    stream, err := c.ChatStream(context.Background())
    if err != nil {
        log.Fatalf("could not open stream: %v", err)
    }

    // Receive messages in a goroutine
    go func() {
        for {
            msg, err := stream.Recv()
            if err == io.EOF {
                log.Println("Server closed the stream")
                return
            }
            if err != nil {
                log.Printf("stream error: %v", err)
                return
            }
            log.Printf("%s says: %s", msg.User, msg.Text)
        }
    }()

    // Send messages
    messages := []string{"Hi there", "How’s it going?", "Bye for now"}
    for _, text := range messages {
        err := stream.Send(&pb.ChatMessage{User: "Client", Text: text})
        if err != nil {
            log.Printf("send error: %v", err)
            return
        }
        time.Sleep(1 * time.Second) // Simulate a chat pace
    }
    stream.CloseSend() // Tell server we’re done sending
    time.Sleep(1 * time.Second) // Let server finish responding
}

Step 4: Run It

Start the server:

go run server/main.go

Then the client:

go run client/main.go

The client sends three messages, and the server echoes them back. You’ll see output like:

Client: Hi there
Server: Echo: Hi there
Client: How’s it going?
Server: Echo: How’s it going?
Client: Bye for now
Server: Echo: Bye for now

This shows gRPC’s duplex streaming in action—both sides talking simultaneously over one connection. It’s perfect for chat apps, live updates, or any real-time system.

What is Protocol Buffers?

Protocol Buffers (protobuf) is the data format gRPC uses.

You define your messages and services in a .proto file, and protoc generates code to serialize/deserialize them into binary.

It’s faster than JSON because it’s compact and skips text parsing. In our examples, HelloRequest and ChatMessage are protobuf messages—simple, typed, and efficient.