Skip to content
  1. Blog
  2. Learning

Why gRPC Suits High-Performance APIs: A Guide with Code

TL;DR: gRPC Remote Procedure Calls (gRPC) is a framework that lets one service call a method on another as if it were local code. It sends compact Protocol Buffers messages over version 2 of Hypertext Transfer Protocol (HTTP), known as HTTP/2, which keeps overhead low between services. For public APIs, representational state transfer (REST) is often simpler, so our eSignature API uses REST.

Your app handles one user request by calling five internal services, each over REST with JavaScript Object Notation (JSON). Under load, those calls add up, and the time goes on text parsing and fresh connections.

gRPC was built for this kind of traffic. This guide explains how it works, compares it with REST, and walks through a small working service with deadlines, security and versioning.

What is gRPC?

gRPC is an open source framework for calling methods on another machine. A client calls a method on a server as if it were a local object, and gRPC handles the network.

Think of an office phone with extensions. You dial “accounts, extension 204” and talk straight to the right person. You skip the front desk, and both sides already know the topic.

So is gRPC an API? It is a framework for building APIs. You define a service with methods, and gRPC turns that definition into a working client and server.

How does gRPC work?

You write the contract first, in a .proto file. It lists the service, its methods and the shape of every request and reply.

From that file, the tooling generates two things. The server gets an interface to implement, and the client gets a stub with the same methods. The file stays the source of truth, so a client and server built from it agree on every field.

Diagram of a gRPC call: the client calls a stub, the stub sends the request to the server, and the server sends the reply back

Why are Protocol Buffers smaller than JSON?

Protocol Buffers turn messages into compact binary data instead of text. The Protocol Buffers docs describe the format as “like JSON, except it’s smaller and faster”.

Each field travels as a number and a value, with no field names repeated in every message. Both sides already hold the schema, so they know what field 1 means.

Protocol Buffers also act as the interface definition language (IDL) for gRPC. One file gives you typed fields, enums and generated code in many languages.

How does HTTP/2 lower gRPC overhead?

gRPC runs over HTTP/2, and that is where much of its low overhead comes from. HTTP/2 carries many calls at once over a single long-lived connection.

HTTP/2 is defined in Request for Comments (RFC) 9113, which replaced the older RFC 7540. It adds three features that matter for gRPC:

  • Multiplexing, so many requests share one connection without waiting for each other.
  • Header compression, so repeated metadata takes fewer bytes.
  • Long-lived connections, so clients skip the cost of reconnecting under load.

gRPC overhead stays low because both layers work together: small binary messages travel over a connection that is already open.

Is there a gRPC RFC?

No Internet Engineering Task Force (IETF) RFC defines gRPC itself. The gRPC team documents the wire format in gRPC over HTTP2 on GitHub, and that document builds on the HTTP/2 RFC.

What are the four types of gRPC calls?

gRPC lets you define four kinds of service method. The simplest works like a REST call, and the other three stream messages.

  1. In a unary call, the client sends one request and gets one response back.
  2. In server streaming, the client asks once and the server sends back a stream, such as progress updates.
  3. In client streaming, the client sends a stream and the server answers once, such as after a batch upload.
  4. In bidirectional streaming, both sides send streams on their own schedule, such as a chat.

Within each stream, messages arrive in the order they were sent.

gRPC vs REST API: how do they compare?

Use gRPC when efficiency and streaming matter most. Use REST when reach and browser support matter most.

gRPC REST (typical JSON over HTTP)
Message format Binary Protocol Buffers Text, usually JSON
Transport HTTP/2 HTTP/1.1 or HTTP/2
Contract Schema first, strongly typed .proto file Often an OpenAPI file, sometimes none
Streaming Built in, four call types Possible with extra tools, not part of REST
Browser support Needs gRPC-Web and a proxy Works in every browser
Testing tools grpcurl and generated clients curl, Postman and any HTTP client

When should you use gRPC, and when REST?

Pick by who calls the API, how much traffic it carries, and what your team already runs. Many systems use both.

When does gRPC fit?

  • Service-to-service calls inside a microservices platform with heavy traffic.
  • Live updates such as dashboards or presence, where streaming replaces polling.
  • Teams using several languages that want generated clients and one shared contract.
  • Platform APIs inside Kubernetes or a service mesh, which route long-lived connections well.

When does REST fit?

  • Your main callers are browsers, and you want no proxy layer.
  • You want simple debugging with curl and readable JSON.
  • Your API is public, and outside developers need to call it from any language.
  • You rely on HTTP caching in browsers or at the network edge.

gRPC vs gRPC-Web: how do browsers call gRPC?

Browsers cannot speak standard gRPC, so they use gRPC-Web through a proxy. The gRPC-Web protocol exists because browsers do not expose HTTP/2 framing to code.

A gRPC-Web client sends its calls to a proxy, by default Envoy, which passes them on to your gRPC service. Unary calls work, and server streaming works in the text wire mode. Client and bidirectional streaming are not supported yet.

Here is the usual deployment shape:

Browser (gRPC-Web) -> Envoy (gRPC-Web filter) -> gRPC service (HTTP/2)

Envoy’s gRPC-Web filter does the bridging between the browser client and the gRPC server.

How do you offer REST and JSON while keeping gRPC inside?

Run gRPC between your own services and put a translating layer at the edge. Outside callers send JSON, and your services keep their gRPC contracts.

  • gRPC-Gateway generates a reverse proxy that turns RESTful JSON calls into gRPC.
  • It reads the google.api.http annotations in your .proto file to map each address to a method.
  • Some cloud platforms offer the same idea as HTTP/JSON transcoding built on your service definitions.

How do you build a small gRPC API?

The four steps below give you a working starting point with one unary method and one server streaming method. You define the contract, run a Node.js server, call it from Python and add a deadline.

Step 1: Define the contract in a .proto file

Schema first is the core gRPC workflow, as the proto3 language guide shows. This file defines a Greeter service with two methods.

// api/demo/v1/greeter.proto
syntax = "proto3";
package demo.v1;
service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
  rpc WatchHellos (HelloRequest) returns (stream HelloReply);
}
message HelloRequest {
  string name = 1;
}
message HelloReply {
  string message = 1;
}

Step 2: Run a Node.js server with dynamic loading

This server loads the .proto file at run time, so you skip code generation. That suits a demo, though many teams use generated stubs in production for stricter typing.

// server.js (Node 18+)
import grpc from "@grpc/grpc-js";
import protoLoader from "@grpc/proto-loader";
const PROTO_PATH = "./api/demo/v1/greeter.proto";
const pkgDef = protoLoader.loadSync(PROTO_PATH, {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
});
const proto = grpc.loadPackageDefinition(pkgDef);
const greeter = proto.demo.v1.Greeter;
function sayHello(call, callback) {
  const name = call.request.name || "world";
  callback(null, { message: `Hello, ${name}!` });
}
function watchHellos(call) {
  const name = call.request.name || "world";
  let i = 0;
  const interval = setInterval(() => {
    i += 1;
    call.write({ message: `Hello #${i}, ${name}!` });
    if (i >= 5) {
      clearInterval(interval);
      call.end();
    }
  }, 500);
  call.on("cancelled", () => clearInterval(interval));
}
const server = new grpc.Server();
server.addService(greeter.service, { SayHello: sayHello, WatchHellos: watchHellos });
server.bindAsync("0.0.0.0:50051", grpc.ServerCredentials.createInsecure(), () => {
  server.start();
  console.log("gRPC server listening on :50051");
});

The file uses import statements, so add "type": "module" to your package.json before you run it. Then install the packages and start the server:

npm i @grpc/grpc-js @grpc/proto-loader
node server.js

Step 3: Call the server from Python

Python uses the official grpcio package. First install it with the code generator, then generate the client stubs from the same .proto file:

pip install grpcio grpcio-tools
python -m grpc_tools.protoc \
-I ./api \
--python_out=. \
--grpc_python_out=. \
    ./api/demo/v1/greeter.proto

The client below makes one unary call, then reads the server stream:

# client.py
import grpc
from demo.v1 import greeter_pb2, greeter_pb2_grpc


def main():
    channel = grpc.insecure_channel("localhost:50051")
    stub = greeter_pb2_grpc.GreeterStub(channel)
    # Unary
    resp = stub.SayHello(greeter_pb2.HelloRequest(name="John"))
    print("Unary:", resp.message)
    # Server streaming
    for msg in stub.WatchHellos(greeter_pb2.HelloRequest(name=" John ")):
        print("Stream:", msg.message)


if __name__ == "__main__":
    main()

Run the client from the folder that holds the generated demo package:

python client.py

Step 4: Add a deadline to every call

Set a time limit on each call from the start. In Python, the timeout argument gives the call half a second:

resp = stub.SayHello(greeter_pb2.HelloRequest(name="John"), timeout=0.5)

The call fails with a DEADLINE_EXCEEDED status when the server takes longer.

How do you test gRPC vs curl on a REST API?

With REST, you test an endpoint by sending a request with curl. Comparing gRPC vs curl mixes a protocol with a tool, and the gRPC version of that tool is grpcurl.

grpcurl is a command-line tool that works like curl, but for gRPC servers. It learns your methods through server reflection, or from your .proto files when the server does not offer reflection.

How do you use gRPC from JavaScript and other languages?

Comparing gRPC vs JavaScript is a similar mix-up: one is a framework, and the other is a language. In Node.js, you use gRPC through the @grpc/grpc-js package, as in step 2.

Microsoft documents gRPC for its own web framework too. Its gRPC client guide covers clients generated from .proto files and all four call types.

What compatibility rules should teams enforce for gRPC APIs?

Treat every .proto file as a public contract once clients use it. The proto3 guide sets out the rules that keep old clients working:

  • Never change a field number once the message type is in use.
  • Never reuse a field number, even after you delete the field.
  • Reserve the number and name of each deleted field, so nobody reuses them by mistake.
  • Add new fields instead of changing existing ones.
  • Treat a change of field type as a breaking change unless you have checked wire compatibility.

Agree as a team who reviews .proto changes, and review them like changes to a public API.

How do you secure gRPC connections?

gRPC has built-in support for Transport Layer Security (TLS). The gRPC authentication guide says TLS authenticates the server and encrypts all data between client and server.

Mutual TLS (mTLS) goes one step further: the client also presents a certificate, so each side proves who it is. Teams often use mTLS between services inside a cluster or service mesh.

You can end the TLS connection in different places. Pick one that matches your platform’s security rules:

  • In the application itself.
  • In a sidecar proxy that runs next to each service.
  • In an edge proxy at the border of your network.

How do deadlines, retries and proxies keep gRPC reliable?

Deadlines limit how long each call can run, and retries recover from short failures. A proxy such as Envoy adds central routing on top.

Why should every gRPC call set a deadline?

By default, gRPC sets no deadline, so a client can wait for a response forever. Set a realistic deadline on every call, based on network delay and server time, then check it with load tests.

When a deadline passes, the server cancels the call. Your server code should check for that and stop long work. Some languages pass the deadline on to downstream calls by default, and others need it switched on.

When do retries help, and when do they hurt?

Retries help with short failures, but they add load during an outage.

gRPC turns retries on by default but sets no default retry policy, so it retries only in narrow, safe cases.

Write a retry policy per method, with a cap on attempts, exponential backoff and a list of retryable status codes. Retry only calls that are safe to repeat.

How does Envoy fit into gRPC traffic?

Envoy can proxy gRPC traffic and bridge gRPC-Web clients. Teams often place it at the edge or in a service mesh for central routing and policy.

Which gRPC practices keep services fast and easy to run?

Most of these come down to setting limits early and keeping the contract tidy. Start with these five:

  • Design the .proto file first and review changes as you would a public API.
  • Set deadlines on every call and pass them across service boundaries.
  • Prefer a few larger methods, or a stream, over many tiny calls.
  • Log status codes and latency per method through interceptors or middleware.
  • Stream large results in parts instead of packing them into one huge response.

What common gRPC mistakes should you avoid?

Most trouble starts with missing time limits or careless contract changes. Watch for these five:

  • Calls with no deadline, which hang and use up server resources.
  • Retrying every failure, which can turn a small outage into a large one.
  • Reusing field numbers or changing types, which breaks older clients in quiet ways.
  • Exposing gRPC to browsers with no gRPC-Web or gateway plan.
  • Streams that ignore cancellation, timeouts or slow readers, which keep holding memory and connections.

How does gRPC relate to the BoldSign API?

The BoldSign API is a REST API that returns JSON. We chose REST because outside developers call it from browsers, servers and every common language.

This guide describes the same split: gRPC between your own services, and REST for a public API. Your internal services can talk over gRPC and still call our REST API to send documents for signature.

When a document changes state, we can notify your app through webhooks. Our gRPC vs REST comparison covers the trade-offs from the API design side. For questions about an endpoint, write to our support portal.

Which BoldSign API plan do you need, and what does it cost?

You can test every endpoint in a free API sandbox account. Live API sending, with webhooks, is on the Enterprise API plan, from $30 a month with 40 envelopes.

Each extra envelope costs $0.75, as listed on the BoldSign pricing page in November 2026. Prices are in USD.

Where should you go next with gRPC?

You now know how gRPC works, where it saves time inside a system, and where REST still fits. Pick your next step:

Frequently asked questions

Does switching from REST to gRPC always cut response times?

Not always. Its binary messages and shared connections cut overhead, but real results depend on payload shape, network, server load and how many calls each task needs. Measure your own traffic before you switch.

Can I use gRPC directly from the browser?

Not with standard gRPC. Browsers use gRPC-Web, which goes through a proxy such as Envoy, and it supports unary and server streaming calls.

What is the difference between Protocol Buffers and gRPC?

Protocol Buffers describe your messages and turn them into compact binary data. gRPC defines the services and methods, and it carries the calls between client and server.

When should I use streaming in gRPC?

Use streaming for data that keeps arriving, such as progress updates, live feeds or sensor readings. It also helps when one long call replaces many small ones.

Does gRPC set a deadline by default?

No. By default gRPC sets no deadline, so a client can wait for a reply forever. Set a realistic deadline on every call.

How do I offer a REST API when my backend uses gRPC?

Put a translating layer in front of it. gRPC-Gateway reads your service definitions and generates a reverse proxy that turns JSON requests into gRPC calls.

How do I keep Protocol Buffers messages backward compatible?

Never change or reuse a field number once it is in use. Add new fields instead, and reserve the numbers and names of fields you delete.

Does gRPC need HTTP/2?

Yes, standard gRPC runs over HTTP/2 framing. In browsers, gRPC-Web uses its own protocol because browsers do not expose HTTP/2 frames to code.

Priya Vinayagam

Priya Vinayagam is a Product Manager at BoldSign and an active full-stack developer at Syncfusion, with four years of hands-on experience across .NET and JavaScript. She writes practical, performance-focused technical articles that help developers tackle real-world challenges. Known for looking beyond the obvious, Priya brings a builder’s mindset to every post—breaking down complex problems into clear, actionable solutions. Connect with her on LinkedIn.

More posts by Priya Vinayagam
Get started

Sign up for your free trial today!

Start free trial
  • 30-day free trial
  • No credit card required