Go Language

Build Simple API with gRPC, Protobuf and Golang

This guide gets you started with gRPC in Go with a simple working example.

Founder @ednsquare | Continiously Designing Testing Coding at ednsquare | Any query? shoot an email at ednsquare@gmail.com

Published · Aug 4 2019

gRPC Basics - Go
This tutorial provides a basic Go programmer’s introduction to working with gRPC.
By walking through this example you’ll learn how to:
Define a service in a .proto file.
Generate server and client code using the protocol buffer compiler.
Use the Go gRPC API to write a simple client and server for your service.

It assumes that you have read the Overview and are familiar with protocol buffers. Note that the example in this tutorial uses the proto3 version of the protocol buffers language: you can find out more in the proto3 language guide and the Go generated code guide.

Why use gRPC?
Our example is a simple route mapping application that lets clients get information about features on their route, create a summary of their route, and exchange route information such as traffic updates with the server and other clients.

With gRPC we can define our service once in a .proto file and implement clients and servers in any of gRPC’s supported languages, which in turn can be run in environments ranging from servers inside Google to your own tablet - all the complexity of communication between different languages and environments is handled for you by gRPC. 

We also get all the advantages of working with protocol buffers, including efficient serialization, a simple IDL, and easy interface updating.
Prerequisites
Go version,
gRPC requires Go 1.6 or higher.
$ go version

For installation instructions, follow this guide: Getting Started - The Go Programming Language

Install gRPC
Use the following command to install gRPC.
$ go get -u google.golang.org/grpc

Install Protocol Buffers v3
Install the protoc compiler that is used to generate gRPC service code. The simplest way to do this is to download pre-compiled binaries for your platform(protoc-<version>-<platform>.zip) from here: https://github.com/google/protobuf/releases
Unzip this file.
Update the environment variable PATH to include the path to the protoc binary file. or do this for linux 

Next, install the protoc plugin for Go
$ go get -u github.com/golang/protobuf/protoc-gen-go

The compiler plugin, protoc-gen-go, will be installed in $GOBIN, defaulting to $GOPATH/bin. It must be in your $PATH for the protocol compiler, protoc, to find it.

Download the example
The grpc code that was fetched with go get google.golang.org/grpc also contains the examples. They can be found under the examples dir: $GOPATH/src/google.golang.org/grpc/examples.

. . .

Build the example
Change to the example directory
$ cd $GOPATH/src/google.golang.org/grpc/examples/helloworld

gRPC services are defined in a .proto file, which is used to generate a corresponding .pb.go file. The .pb.go file is generated by compiling the .protofile using the protocol compiler: protoc.

For the purpose of this example, the helloworld.pb.go file has already be
en generated (by compiling helloworld.proto), and can be found in this directory: 
$GOPATH/src/google.golang.org/grpc/examples/helloworld/helloworld

This helloworld.pb.go file contains:
Generated client and server code.
Code for populating, serializing, and retrieving our HelloRequest and HelloReply message types.

. . .
Try it!
To compile and run the server and client code, the go run command can be used. In the examples directory:
$ go run greeter_server/main.go

From a different terminal:
$ go run greeter_client/main.go

If things go smoothly, you will see the Greeting: Hello world in the client side output.

Congratulations! You’ve just run a client-server application with gRPC.
. . .
Update a gRPC service
Now let’s look at how to update the application with an extra method on the server for the client to call. Our gRPC service is defined using protocol buffers; you can find out lots more about how to define a service in a .proto file in What is gRPC? and gRPC Basics: Go. 

For now all you need to know is that both the server and the client “stub” have a SayHello RPC method that takes a HelloRequest parameter from the client and returns a HelloReplyfrom the server, and that this method is defined like this:
// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}

Let’s update this so that the Greeter service has two methods. Make sure you are in the same examples dir as above 
($GOPATH/src/google.golang.org/grpc/examples/helloworld)

Edit helloworld/helloworld.proto and update it with a new SayHelloAgain method, with the same request and response types:
// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {}
  // Sends another greeting
  rpc SayHelloAgain (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}

. . .
Generate gRPC code
Next we need to update the gRPC code used by our application to use the new service definition. From the same examples dir as above ($GOPATH/src/ google.golang.org/grpc/examples/helloworld)
$ protoc -I helloworld/ helloworld/helloworld.proto --go_out=plugins=grpc:helloworld

This regenerates the helloworld.pb.go with our new changes.
. . .
Update and run the application
We now have new generated server and client code, but we still need to implement and call the new method in the human-written parts of our example application.

Update the server
Edit greeter_server/main.go and add the following function to it:
func (s *server) SayHelloAgain(ctx context.Context, in *pb.HelloRequest) (*pb.HelloReply, error) {
        return &pb.HelloReply{Message: "Hello again " + in.Name}, nil
}

Update the client
Edit greeter_client/main.go to add the following code to the main function
r, err = c.SayHelloAgain(ctx, &pb.HelloRequest{Name: name})
if err != nil {
        log.Fatalf("could not greet: %v", err)
}
log.Printf("Greeting: %s", r.Message)

. . .
Run!
Run the server
$ go run greeter_server/main.go

On a different terminal, run the client
$ go run greeter_client/main.go

You should see the updated output:
$ go run greeter_client/main.go
Greeting: Hello world 
Greeting: Hello again world

. . .
Summary
Protocol Buffers offer very real advantages in terms of speed of encoding and decoding, size of the data on the wire, and more. You may wonder now, what are the benefits of gRPC over a regular JSON REST API. 

  
And that’s it , you’re well on your way to become a king at Go and gRPC ! Thank you for reading, I hope you enjoyed it!