Catalog My learning Blog
gRPC and Protobuf Tutorial: Fast Microservice APIs · Phase 1 · Lesson 6 · 3 min read

gRPC Tutorial: Build a Server and Client

On this page
  1. What you'll build
  2. Step 1: implement the gRPC server in Go
  3. Step 2: start the server with health and reflection
  4. Step 3: explore the API with grpcurl
  5. Step 4: write a Go client
  6. Common gRPC setup problems
  7. Check yourself

What you'll build

A Go server implementing OrderService, a client calling it, and the ability to inspect it from the command line. Every snippet here is from the course's lab, built with Go 1.27 and grpc-go 1.84.

Step 1: implement the gRPC server in Go

Embed the generated base type and implement methods:

GraphQL
type server struct {
	shopv1.UnimplementedOrderServiceServer
	mu     sync.Mutex
	orders map[string]*shopv1.Order
}

func (s *server) GetOrder(ctx context.Context, req *shopv1.GetOrderRequest) (*shopv1.GetOrderResponse, error) {
	s.mu.Lock()
	defer s.mu.Unlock()
	o, ok := s.orders[req.GetOrderId()]
	if !ok {
		return nil, status.Errorf(codes.NotFound, "order %q not found", req.GetOrderId())
	}
	return &shopv1.GetOrderResponse{Order: o}, nil
}

Methods can run concurrently on many goroutines, hence the mutex. Generated getters like req.GetOrderId() are nil-safe.

Step 2: start the server with health and reflection

Go
func main() {
	lis, err := net.Listen("tcp", "127.0.0.1:50051")
	if err != nil {
		log.Fatal(err)
	}
	srv := grpc.NewServer(grpc.UnaryInterceptor(authLog))   // interceptors: Day 16
	shopv1.RegisterOrderServiceServer(srv, s)

	hs := health.NewServer()                               // standard health service (Day 20)
	healthpb.RegisterHealthServer(srv, hs)
	hs.SetServingStatus("shop.v1.OrderService", healthpb.HealthCheckResponse_SERVING)

	reflection.Register(srv)                               // lets tools discover the API
	log.Fatal(srv.Serve(lis))
}

This development server uses no TLS; Day 17 adds it.

Step 3: explore the API with grpcurl

With reflection on, grpcurl lists and describes services without the .proto file:

Code
grpcurl -plaintext 127.0.0.1:50051 list
Code
grpc.health.v1.Health
grpc.reflection.v1.ServerReflection
grpc.reflection.v1alpha.ServerReflection
shop.v1.OrderService
Code
grpcurl -plaintext -H 'authorization: Bearer demo-token' \
  -d '{"order_id":"ord_42"}' 127.0.0.1:50051 shop.v1.OrderService/GetOrder
JSON
{
  "order": {
    "id": "ord_42",
    "customerId": "cus_7",
    "status": "STATUS_PAID",
    "totalCents": "4999",
    "createdAt": "2026-10-15T02:53:44.048484Z"
  }
}

grpcurl converts JSON to protobuf and back. Note "totalCents": "4999": the protobuf JSON mapping writes 64-bit integers as strings, because JavaScript numbers can't represent all of them exactly (Day 21).

The server implements the generated interface and registers services on a listener; the client creates a connection, builds a stub, and calls methods; grpcurl explores the server through reflection.
The server implements the generated interface and registers services on a listener; the client creates a connection, builds a stub, and calls methods; grpcurl explores the server through reflection.

Step 4: write a Go client

Code
conn, err := grpc.NewClient("127.0.0.1:50051",
	grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
	log.Fatal(err)
}
defer conn.Close()

client := shopv1.NewOrderServiceClient(conn)
ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer demo-token")
resp, err := client.GetOrder(ctx, &shopv1.GetOrderRequest{OrderId: "ord_42"})
  • grpc.NewClient (which replaced the older grpc.Dial) doesn't connect immediately; the connection is established on the first call and reconnects automatically.
  • Create one connection and reuse it for the life of the process. A connection carries many concurrent calls over HTTP/2; opening one per request wastes handshakes.
  • Metadata carries headers such as auth tokens.

Common gRPC setup problems

SymptomCause
Unimplemented: unknown serviceService not registered, or client and server packages differ
Unavailable: connection refusedServer not running, wrong address or port
Unavailable ... EOF from a plaintext clientThe server expects TLS (Day 17)
UnauthenticatedMissing or wrong metadata, rejected by an interceptor

Check yourself

A single connection multiplexes many concurrent calls over HTTP/2 streams. Creating a connection per call adds TCP and TLS handshakes, resolver work and latency to every request for no benefit, and can exhaust ports under load.

Tools like grpcurl and Postman can list services and methods and call them without having the .proto files, because the server describes its own API at runtime. It's very convenient for debugging.

The protobuf JSON mapping encodes 64-bit integers as strings, because JavaScript numbers lose precision above 2^53. The binary value is still a normal int64.

A grpc.health.v1.Health service with Check and Watch methods that load balancers, Kubernetes probes and tools can call to ask whether the server, or a specific service on it, is serving. Every gRPC library ships an implementation.

They send traffic in plain text and don't verify the server's identity, so anyone on the network path can read or alter calls, including auth tokens. Production connections should use TLS, ideally mutual TLS between services.