Learn gRPC - Writing Your First gRPC API with Protocol Buffers

#Introduction

All of gRPC's power comes down to a single file: .proto. This file is the contract read by humans, the compiler, clients, and servers alike. In episode 3 you'll learn to write that contract correctly — not just a simple example, but a structure ready for real services.

We'll cover three layers of the contract: file structure (package, imports, options), protobuf v3 data types (scalar, enum, oneof, map, repeated), and service definitions with all four RPC patterns. By the end of the episode, you'll have one complete .proto file ready to be generated in episode 4.

#.proto File Structure

#Package, Imports, and Options

The top of a .proto file contains three important declarations:

• syntax = "proto3": selects the protobuf schema language version 3.
• package: the namespace that determines type names in the generated code, e.g. catalog.v1.
• import: includes other files, e.g. google/protobuf/timestamp.proto for time types.

syntax = "proto3";
 
package catalog.v1;
 
import "google/protobuf/timestamp.proto";
 
option go_package = "learn-grpc/gen/catalog/v1;catalogv1";
 
message Product {
  string id = 1;
  string name = 2;
  double price = 3;
}

The go_package option determines the output location in Go; for other languages, the convention varies by plugin. Writing option go_package is mandatory for the Go plugin.

#Field Numbering Rules

Every field uses a unique number within a message: string id = 1 means the field is numbered 1. This number is part of the wire format, so never change the meaning of a number already in use. Numbers 1 through 15 use only one byte — give small numbers to the fields accessed most often.

#Protobuf v3 Data Types

#Scalar Types

Protobuf v3 provides scalar types mapped to native language types: int32, int64, uint32, float, double, bool, string, and bytes. Note that all v3 fields are optional: default values like 0 and empty strings are used automatically when a field isn't set.

#enum, oneof, and map

These three constructs solve most data modeling problems:

message Product {
  enum Status {
    STATUS_UNSPECIFIED = 0;
    STATUS_ACTIVE = 1;
    STATUS_ARCHIVED = 2;
  }
  Status status = 4;
 
  oneof dimension {
    int32 weight_grams = 5;
    int32 volume_ml = 6;
  }
 
  map<string, string> attributes = 7;
}

• enum restricts the valid values; the first value must be 0.
• oneof ensures only one field is set; Product has weight_grams or volume_ml.
• map stores key-value pairs, e.g. free-form attributes like color and material.

#repeated for Lists

For lists of values, use repeated — the equivalent of a list or array in programming languages:

message Order {
  repeated string product_ids = 1;
  int32 total = 2;
}

repeated string product_ids = 1 can hold zero or many IDs. For scalar types, protobuf enables packed encoding automatically so list elements are transmitted very compactly.

#Defining a Service

#The Four RPC Patterns

The heart of the contract is the service block. Four communication patterns are fully supported by protobuf:

• Unary: one request, one response — like a normal function call.
• Server streaming: the client sends one request, the server sends many responses.
• Client streaming: the client sends many requests, the server sends one response.
• Bidirectional streaming: both sides send many messages at the same time.

service ProductService {
  rpc GetProduct(ProductId) returns (Product);
  rpc ListProducts(ProductQuery) returns (stream Product);
  rpc AddBulk(stream Product) returns (BulkResult);
  rpc Search(stream SearchTerm) returns (stream Product);
}

Read the declarations above: rpc GetProduct(ProductId) returns (Product) is unary, ListProducts uses the stream keyword in the response, AddBulk uses stream in the request, and Search uses stream in both.

#Messages for Request and Response

Every method needs its own request and response types. Don't reuse one message for different purposes — separate request-response pairs make schema evolution easier without breaking each other:

message ProductId {
  string id = 1;
}
 
message ProductQuery {
  string keyword = 1;
  int32 limit = 2;
}
 
message BulkResult {
  int32 added_count = 1;
}

#Good Writing Conventions

Some practices that keep your contracts healthy in the long run:

• Camel case for fields (product_id) and Pascal case for messages (ProductQuery).
• Prefix enum statuses with the enum name (STATUS_ACTIVE) so the generated code is unambiguous.
• // comments above every field and method as automatic documentation.
• One service per file when the domain is large, and avoid one giant file.

A clean contract will make the generated code easy to read by the whole team across languages.

#Closing

Key takeaways:

• .proto is the single contract read by humans, the compiler, clients, and servers.
• package, import, and option go_package form the skeleton of a valid file.
• Use enum, oneof, map, and repeated to model your domain precisely.
• The four RPC patterns are declared with the stream keyword in the right positions.
• Field numbers must never change once in use, because they're part of the wire format.
• Every method has its own dedicated request and response messages.

In episode 4 next, you'll generate code and run your first server-client: installing plugins, the protoc command for Go, implementing a simple server, implementing a simple client, and local testing with a real request-response round trip. The .proto file you just wrote will come to life as runnable code.