Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 39 ยท Getting Started

What Is gRPC?

Learn what gRPC and Protocol Buffers are, why teams use them for service-to-service calls, and how a remote procedure call feels like a local function call.

gRPC is a framework for calling functions on another machine as if they were local functions. You describe the functions and their data in a small contract file, a tool generates client and server code in your language, and the framework takes care of networking, serialization, deadlines and errors. It was created at Google, is now an open project, and is used heavily for communication between backend services.

This course teaches gRPC and its data format, Protocol Buffers (protobuf), from the first contract file to production topics such as load balancing and versioning. Before we begin, one honest note about the site.

What runs here and what does not. The real protoc compiler, the gRPC libraries and a gRPC server cannot run inside your browser or on our code runner. Real gRPC code in this course is shown read-only (in plain code blocks). Next to it you will find runnable Go stand-ins: small programs built only from the Go standard library that reproduce the underlying idea (a contract, a stub, a wire format, a stream). Every stand-in is labelled as such, and we only print output we have actually seen.

The idea: remote procedure calls

A remote procedure call (RPC) hides the network behind a function signature. Instead of building a URL, choosing an HTTP verb, writing JSON and parsing a response, the caller writes something like this:

Go
reply, err := client.SayHello(ctx, &pb.HelloRequest{Name: "Ada"})

The call looks local, but a stub serializes the request, sends it to a server, waits, and turns the answer back into an object. The server implements a plain method. Both sides agree on the shape of the data through a shared contract.

flowchart LR
  A["Client code"] --> B["Generated stub"]
  B -- "bytes over HTTP/2" --> C["Generated server skeleton"]
  C --> D["Your service method"]
  D --> C
  C -- "bytes over HTTP/2" --> B
  B --> A

Both stub and skeleton are generated from the same contract file, so they can never disagree about the data.

The three ingredients

  1. Protocol Buffers are both the language you write contracts in (.proto files) and a compact binary format for the data. See the protobuf language.
  2. Code generation turns a .proto file into typed classes and service interfaces for Go, Java, Python, C#, C++, Rust, Kotlin, Swift, Dart, Node.js and more. You never write serialization code by hand.
  3. HTTP/2 transport carries calls. It provides multiplexing (many calls on one connection), streaming and header compression. Read more in how gRPC uses HTTP/2.

A contract in one screen

This is what a real gRPC contract looks like. It is shown read-only, because the site cannot compile it:

PROTO
syntax = "proto3";

package greeter.v1;

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

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

Notice what is missing: there are no URLs, no status-code tables and no JSON field names. The contract names one method, its input type and its output type. The numbers (= 1) are field identifiers used on the wire; we explain them in field numbers and the wire format.

Stand-in 1: a contract-first call in plain Go

This runnable program is a stand-in: it is not gRPC, and it uses JSON instead of protobuf. It shows the same architecture. A Transport moves bytes, a Client stub hides serialization, and a Server dispatches a method name to a handler.

Go Stand-in: stub, transport, server

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The caller never touches JSON. If you replace encoding/json with protobuf and the in-memory transport with an HTTP/2 connection, you have the architecture of gRPC.

Why teams choose gRPC

  • Strong contracts. The .proto file is the single source of truth. Renaming a field or changing a type breaks compilation, not production.
  • Small and fast. Protobuf is binary and skips field names on the wire. Messages are typically much smaller than the same JSON, and encoding and decoding are cheaper.
  • Streaming built in. Servers can push many messages for one call, clients can upload a stream, and both can talk at once. See streaming.
  • Deadlines and cancellation. Every call can carry a deadline that travels to downstream services. See deadlines.
  • Many languages, one contract. A Go service and a Python client share generated code from the same file.

Where gRPC is a poor fit

  • Browsers. Browsers cannot send raw gRPC. You need gRPC-Web or a gateway; see gateways.
  • Human-readable debugging. Binary messages are not readable in a plain curl. You use tools such as grpcurl, which need reflection or the .proto file.
  • Public, cache-heavy APIs. HTTP caches and CDNs understand GET and URLs, not RPC methods.

Stand-in 2: how much smaller is binary?

Protobuf's compactness is one reason for its popularity. This stand-in encodes the same fields in two ways: JSON text, and a simplified tag-length-value layout like protobuf's (tag byte, then a length, then the bytes). It is an illustration of the principle, not a protobuf encoder.

Go Stand-in: text versus tagged binary

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Real protobuf does even better for numbers because it uses variable-length integers (varints), which we implement by hand in a later lesson.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a generated client stub do?

    The stub encodes the request, sends it, waits for the reply and decodes it, so the caller sees a normal method.
  2. 2. Which pair describes gRPC's main building blocks?

    Contracts and data use Protocol Buffers; calls travel over HTTP/2.
  3. 3. Why is gRPC awkward to call directly from a browser?

    Browser APIs do not give pages control over HTTP/2 framing and trailers, which gRPC relies on.
  4. 4. On this site, why are the Go programs called stand-ins?

    We label them honestly: they illustrate concepts, they are not the real framework.

Summary

  • gRPC makes remote calls look like local method calls using generated stubs and skeletons.
  • A .proto contract defines messages and services once for every language.
  • Protocol Buffers give a compact binary format; HTTP/2 gives multiplexing and streaming.
  • It shines for internal service-to-service traffic and is a weaker fit for browsers and public cached APIs.
  • On this site real gRPC code is read-only, and Go stand-ins demonstrate the ideas.

Next: gRPC vs REST