gRPC

By the Syncfusion DevTutorials team · Last updated October 20, 2026

Let services talk fast with small binary protobuf messages and a strict .proto contract.

gRPC is an API style designed for communication between services.

Instead of sending JSON text, gRPC sends compact binary messages encoded using Protocol Buffers (protobuf). Both the client and server agree on the structure of every message through a shared contract file called a .proto file. Because the message format is predefined, gRPC can send data more efficiently than JSON and is commonly used for communication between internal services.

Watch an Internal Call Carry Its Own Labels

As Brew & Bytes grows, the Order Service no longer processes payments itself. Instead, it calls a separate Payment Service. The services currently communicate using JSON. Press Run.

Notice the response size:

X-Body-Bytes: 87

Much of the message consists of field names:

{
  "paymentId": "...",
  "currency": "INR",
  "status": "approved"
}

The Payment Service already knows these field names. The Order Service already knows these field names. Transmitting the same labels repeatedly is unnecessary work.

In simple words: JSON repeatedly sends field names. gRPC sends compact binary data because both sides already know the structure.

TL;DR

• gRPC uses Protocol Buffers (protobuf).
• Messages are encoded as compact binary bytes.
• The .proto file defines the contract.
• Field names are never sent across the network.
• Every field has a unique field number.
• Small numbers use very little space through varint encoding.
• Never change or reuse field numbers.
• Removed field numbers should be marked as reserved.
• gRPC runs on HTTP/2.

• gRPC supports:

  • Unary calls
  • Streaming
• gRPC is best suited for internal service-to-service communication.
• Browsers typically require gRPC-Web rather than raw gRPC.

A Real-World Example

Imagine restaurant staff communicating inside a busy kitchen. A waiter could write:

Dear kitchen,

Please prepare two lattes for table four.

Thank you.

This contains a lot of unnecessary text. Instead, kitchens often use shorthand:

T4 2xLAT

Everyone already understands the notation. It is faster to write and faster to read. The .proto file is the shared codebook. The protobuf message is the shorthand note.

What You Will Learn

In this lesson, you will learn:

1. Why gRPC is efficient for internal communication.
2. How .proto contracts work.
3. How protobuf encodes data into bytes.
4. How protobuf decodes bytes back into values.
5. How to safely evolve a contract.
6. How unary and streaming calls differ.

The Contract: A .proto File

Every gRPC application starts with a .proto file.

Example:

syntax = "proto3";

package brew.payments;

message PaymentRequest {
  int32 order_id = 1;
  int32 amount = 2;
  string currency = 3;
}

message PaymentReply {
  string payment_id = 1;
  string status = 2;
}

message StatusRequest {
  int32 order_id = 1;
}

message StatusUpdate {
  int32 order_id = 1;
  string status = 2;
}

service PaymentService {
  rpc Charge (PaymentRequest)
      returns (PaymentReply);

  rpc GetStatus (StatusRequest)
      returns (StatusUpdate);

  rpc WatchStatus (StatusRequest)
      returns (stream StatusUpdate);
}

Field Numbers

Consider:

int32 order_id = 1;

The value:

= 1

is the field number.

It is not a default value.

Field numbers identify fields on the wire.

Example:

order_id = 1
amount   = 2
currency = 3

Only these numbers are transmitted.

The field names never travel across the network.

Service Definitions

A service acts much like a collection of endpoints.

Example:

service PaymentService {
  rpc Charge (...)
}

The Charge RPC behaves similarly to a REST endpoint but uses protobuf messages instead of JSON.

Encode a Message into Bytes

Suppose we create:

{
  "orderId": 101,
  "amount": 440,
  "currency": "INR"
}

In protobuf, each field is stored as: Tag + Value.

The tag contains:

Field Number
+
Wire Type

Formula:

(field_number << 3) | wire_type

order_id = 101

Tag: 08

Value: 65

amount = 440

Tag: 10

Value: B8 03

currency = "INR"

Tag: 1A

Length: 03

Bytes: 49 4E 52

Total protobuf size: 10 bytes

Equivalent JSON: 45 bytes

The savings become significant when millions of messages are exchanged.

Decode Bytes Back into Data

Decoding performs the reverse process.

The reader:

1. Reads a tag.
2. Extracts the field number.
3. Determines the wire type.
4. Reads the value.

Result:

Field 1 → 101
Field 2 → 440
Field 3 → INR

Notice that the bytes never store:

order_id
amount
currency

The .proto file provides those meanings. Without the contract, the data cannot be interpreted correctly.

int32 points = 0;

optional

Evolving the Contract Safely

Field numbers are permanent. Changing their meaning can produce silent data corruption. Consider this change:

Original:

int32 amount = 2;

Updated:

int32 discount = 2;
int32 amount = 4;

Old services still interpret field:

2

as:

amount

Result: amount = 40

instead of: amount = 440

No exception occurs. No validation error appears. The payment service silently processes the wrong value.

Safe Removal

When removing a field:

message PaymentRequest {
  reserved 2;
  reserved "amount_old";

  int32 order_id = 1;
  string currency = 3;
  int32 amount = 4;
  int32 discount = 5;
}

Now field number 2 can never be reused accidentally.

Safe Changes

Safe contract changes include:

• Adding a new field with a new number
• Reserving removed fields
• Adding new messages
• Adding new service methods

Unsafe changes include:

• Reusing field numbers
• Changing field meaning
• Renumbering fields

Unary and Streaming Calls

gRPC supports multiple communication patterns.

Unary Calls

One request. One response.

Example:

• Client → Charge
• Server → PaymentReply

This works much like a traditional REST request.

Server Streaming

One request. Many responses.

Example:

Client → WatchStatus

Server → received
Server → preparing
Server → ready

The connection remains open while updates arrive.

Streaming avoids repeated polling and supports real-time updates efficiently.

gRPC Framing

Each protobuf message is placed inside a gRPC frame.

Frame structure:

1 byte  Compression Flag
4 bytes Message Length
N bytes Message Data

Example:

00 00 00 00 0D

means:

Not compressed
13-byte message follows

Streaming simply sends multiple frames on the same HTTP/2 connection.

Real gRPC in ASP.NET Core

A real server typically looks like:

builder.Services.AddGrpc();

var app = builder.Build();

app.MapGrpcService<PaymentService>();

app.Run();

Generated classes come directly from the .proto contract. The implementation focuses only on business logic.

public override Task<PaymentReply> Charge(
    PaymentRequest request,
    ServerCallContext context)
{
    return Task.FromResult(
        new PaymentReply
        {
            PaymentId = $"pay-{request.OrderId}",
            Status = "approved"
        });
}

The framework handles:

• Serialization
• Deserialization
• HTTP/2 transport
• Generated client code

REST vs gRPC

When to Use gRPC

gRPC is a strong choice when:

• Both client and server are owned by your organization.
• Performance matters.
• Services communicate frequently.
• Strong contracts are important.
• Streaming is required.

When REST Is Better

REST is usually a better choice when:

• External developers consume the API.
• Requests are inspected frequently.
• Browser compatibility is important.
• Simplicity is preferred.

Where You See This

• Large microservice architectures use gRPC between services.
• Google Cloud services heavily rely on gRPC.
• Kubernetes components communicate using gRPC.
• Many .NET teams use Grpc.AspNetCore.
• JavaScript and TypeScript teams often use @grpc/grpc-js or Connect.

Common mistakes

Exercises

What to Remember

• gRPC sends small binary protobuf messages. The .proto file is the shared contract.
• Each field is a tag plus a value. tag = (field_number << 3) | wire_type. Names never travel.
• Numbers are varints: 7 bits in each byte, and the top bit means "more bytes follow".
• Never reuse a field number. Add new numbers, and reserve the removed ones. Old readers skip unknown fields safely.
• gRPC supports unary and streaming calls over HTTP/2. Each message gets a 5-byte frame header.
• Use REST for public and browser callers, and use gRPC between your own services.

Next: REST vs GraphQL vs gRPC. You will put the three styles side by side, and you will learn how to pick the right one for each job.