When building modern APIs, you'll eventually face a critical decision: should you use REST or gRPC? Both have their place in the API ecosystem, but they solve different problems in different ways.
REST has been the dominant API architecture for over a decade. It's simple, widely understood, and works seamlessly with HTTP. But gRPC, Google's high-performance RPC framework, has been gaining serious traction, especially in microservices architectures.
In this guide, we'll compare these two approaches with practical examples, explore when to use each, and show you how to migrate from REST to gRPC when it makes sense.
REST (Representational State Transfer) is an architectural style that uses HTTP methods and standard status codes. It's resource-oriented, meaning everything is a "thing" you can interact with through URLs.
Here's a typical REST API for our PetStore:
// GET /api/pets - List all pets
fetch('https://api.petstore.com/pets')
.then(res => res.json())
.then(pets => console.log(pets));
// POST /api/pets - Create a new pet
fetch('https://api.petstore.com/pets', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
name: 'Buddy',
species: 'dog',
age: 3
})
});
// PUT /api/pets/123 - Update a pet
fetch('https://api.petstore.com/pets/123', {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
name: 'Buddy',
species: 'dog',
age: 4
})
});
REST is straightforward. You use URLs to identify resources and HTTP verbs to describe actions. The response is typically JSON, which every programming language can parse.
gRPC (gRPC Remote Procedure Call) takes a different approach. Instead of resources and HTTP verbs, you define services with methods. It uses Protocol Buffers (protobuf) for serialization and HTTP/2 for transport.
Here's the same PetStore API defined in gRPC:
// petstore.proto
syntax = "proto3";
package petstore;
service PetService {
rpc ListPets(ListPetsRequest) returns (ListPetsResponse);
rpc CreatePet(CreatePetRequest) returns (Pet);
rpc UpdatePet(UpdatePetRequest) returns (Pet);
rpc GetPet(GetPetRequest) returns (Pet);
rpc StreamPetUpdates(StreamRequest) returns (stream Pet);
}
message Pet {
int32 id = 1;
string name = 2;
string species = 3;
int32 age = 4;
int64 created_at = 5;
}
message ListPetsRequest {
int32 page = 1;
int32 page_size = 2;
string species_filter = 3;
}
message ListPetsResponse {
repeated Pet pets = 1;
int32 total_count = 2;
}
message CreatePetRequest {
string name = 1;
string species = 2;
int32 age = 3;
}
message UpdatePetRequest {
int32 id = 1;
string name = 2;
string species = 3;
int32 age = 4;
}
message GetPetRequest {
int32 id = 1;
}
message StreamRequest {
string species_filter = 1;
}
Using this service in Go looks like this:
package main
import (
"context"
"log"
"time"
"google.golang.org/grpc"
pb "github.com/yourorg/petstore/proto"
)
func main() {
// Connect to gRPC server
conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure())
if err != nil {
log.Fatalf("Failed to connect: %v", err)
}
defer conn.Close()
client := pb.NewPetServiceClient(conn)
ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
// Create a pet
pet, err := client.CreatePet(ctx, &pb.CreatePetRequest{
Name: "Buddy",
Species: "dog",
Age: 3,
})
if err != nil {
log.Fatalf("Could not create pet: %v", err)
}
log.Printf("Created pet: %v", pet)
// List pets
response, err := client.ListPets(ctx, &pb.ListPetsRequest{
Page: 1,
PageSize: 10,
})
if err != nil {
log.Fatalf("Could not list pets: %v", err)
}
log.Printf("Found %d pets", response.TotalCount)
}
Protocol Buffers are gRPC's serialization format. Unlike JSON, which is text-based and human-readable, protobuf is binary and incredibly efficient.
Here's a size comparison for the same pet data:
// JSON (REST) - 156 bytes
{
"id": 12345,
"name": "Buddy",
"species": "dog",
"age": 3,
"created_at": 1678723200,
"owner": {
"id": 67890,
"name": "John Smith",
"email": "john@example.com"
}
}
The same data in protobuf is roughly 40-50 bytes. That's a 70% reduction in payload size.
But the real advantage isn't just size—it's type safety and code generation. When you define your API in a .proto file, you can generate client and server code for dozens of languages:
# Generate Go code
protoc --go_out=. --go-grpc_out=. petstore.proto
# Generate Python code
python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. petstore.proto
# Generate JavaScript code
protoc --js_out=import_style=commonjs:. --grpc-web_out=import_style=commonjs,mode=grpcwebtext:. petstore.proto
This generated code includes all your types, validation, and serialization logic. No more manually parsing JSON or dealing with type mismatches.
REST is fundamentally request-response. You send a request, you get a response. If you want real-time updates, you need to use WebSockets or polling.
gRPC supports four types of streaming out of the box:
rpc GetPet(GetPetRequest) returns (Pet);
The server sends multiple responses for one client request:
rpc StreamPetUpdates(StreamRequest) returns (stream Pet);
// Server implementation
func (s *server) StreamPetUpdates(req *pb.StreamRequest, stream pb.PetService_StreamPetUpdatesServer) error {
ticker := time.NewTicker(2 * time.Second)
defer ticker.Stop()
for {
select {
case <-ticker.C:
// Get updated pets from database
pets := s.db.GetRecentlyUpdatedPets(req.SpeciesFilter)
for _, pet := range pets {
if err := stream.Send(pet); err != nil {
return err
}
}
case <-stream.Context().Done():
return nil
}
}
}
// Client usage
stream, err := client.StreamPetUpdates(ctx, &pb.StreamRequest{
SpeciesFilter: "dog",
})
if err != nil {
log.Fatal(err)
}
for {
pet, err := stream.Recv()
if err == io.EOF {
break
}
if err != nil {
log.Fatal(err)
}
log.Printf("Pet updated: %v", pet)
}
The client sends multiple requests, server responds once:
rpc BatchCreatePets(stream CreatePetRequest) returns (BatchCreateResponse);
Both client and server send streams of messages:
rpc ChatWithSupport(stream ChatMessage) returns (stream ChatMessage);
This is perfect for real-time features like live chat, collaborative editing, or monitoring dashboards.
Let's look at real numbers. I ran benchmarks comparing REST and gRPC for our PetStore API:
REST (JSON over HTTP/1.1):
- Average: 45ms
- P95: 78ms
- P99: 120ms
gRPC (Protobuf over HTTP/2):
- Average: 12ms
- P95: 18ms
- P99: 25ms
gRPC is roughly 3-4x faster for simple requests. The difference comes from:
REST:
- Requests/sec: 2,200
- CPU usage: 65%
- Memory: 450MB
gRPC:
- Requests/sec: 8,500
- CPU usage: 40%
- Memory: 280MB
gRPC handles nearly 4x more requests with less resource usage.
Here's the benchmark code I used:
package main
import (
"context"
"encoding/json"
"fmt"
"net/http"
"testing"
"time"
"google.golang.org/grpc"
pb "github.com/yourorg/petstore/proto"
)
func BenchmarkRESTGetPet(b *testing.B) {
client := &http.Client{Timeout: 5 * time.Second}
b.ResetTimer()
for i := 0; i < b.N; i++ {
resp, err := client.Get("http://localhost:8080/api/pets/123")
if err != nil {
b.Fatal(err)
}
var pet map[string]interface{}
json.NewDecoder(resp.Body).Decode(&pet)
resp.Body.Close()
}
}
func BenchmarkGRPCGetPet(b *testing.B) {
conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure())
if err != nil {
b.Fatal(err)
}
defer conn.Close()
client := pb.NewPetServiceClient(conn)
ctx := context.Background()
b.ResetTimer()
for i := 0; i < b.N; i++ {
_, err := client.GetPet(ctx, &pb.GetPetRequest{Id: 123})
if err != nil {
b.Fatal(err)
}
}
}
One major limitation of gRPC is browser support. Browsers can't make raw gRPC calls because they don't have low-level control over HTTP/2.
Enter gRPC-Web: a JavaScript library that lets you call gRPC services from browsers using a proxy.
Here's how it works:
Browser (gRPC-Web) → Envoy Proxy → gRPC Server
Setting up the proxy with Envoy:
# envoy.yaml
static_resources:
listeners:
- name: listener_0
address:
socket_address:
address: 0.0.0.0
port_value: 8080
filter_chains:
- filters:
- name: envoy.filters.network.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
codec_type: auto
stat_prefix: ingress_http
route_config:
name: local_route
virtual_hosts:
- name: local_service
domains: ["*"]
routes:
- match:
prefix: "/"
route:
cluster: petstore_service
cors:
allow_origin_string_match:
- prefix: "*"
allow_methods: GET, PUT, DELETE, POST, OPTIONS
allow_headers: keep-alive,user-agent,cache-control,content-type,content-transfer-encoding,x-accept-content-transfer-encoding,x-accept-response-streaming,x-user-agent,x-grpc-web,grpc-timeout
max_age: "1728000"
expose_headers: grpc-status,grpc-message
http_filters:
- name: envoy.filters.http.grpc_web
- name: envoy.filters.http.cors
- name: envoy.filters.http.router
clusters:
- name: petstore_service
connect_timeout: 0.25s
type: logical_dns
http2_protocol_options: {}
lb_policy: round_robin
load_assignment:
cluster_name: petstore_service
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: localhost
port_value: 50051
Using gRPC-Web in your frontend:
// Install: npm install grpc-web google-protobuf
import { PetServiceClient } from './generated/petstore_grpc_web_pb';
import { CreatePetRequest, ListPetsRequest } from './generated/petstore_pb';
const client = new PetServiceClient('http://localhost:8080');
// Create a pet
const createRequest = new CreatePetRequest();
createRequest.setName('Buddy');
createRequest.setSpecies('dog');
createRequest.setAge(3);
client.createPet(createRequest, {}, (err, response) => {
if (err) {
console.error('Error:', err.message);
return;
}
console.log('Created pet:', response.toObject());
});
// List pets with streaming
const listRequest = new ListPetsRequest();
listRequest.setPage(1);
listRequest.setPageSize(10);
const stream = client.streamPetUpdates(listRequest, {});
stream.on('data', (pet) => {
console.log('Pet update:', pet.toObject());
});
stream.on('error', (err) => {
console.error('Stream error:', err);
});
stream.on('end', () => {
console.log('Stream ended');
});
REST is still the right choice for many scenarios:
If you're building an API for third-party developers, REST is more accessible. Everyone knows how to make HTTP requests. Not everyone wants to deal with protobuf and code generation.
// Easy for anyone to use
fetch('https://api.petstore.com/pets')
.then(res => res.json())
.then(data => console.log(data));
For straightforward create-read-update-delete operations, REST's resource-oriented approach is intuitive:
GET /pets - List pets
POST /pets - Create pet
GET /pets/123 - Get pet
PUT /pets/123 - Update pet
DELETE /pets/123 - Delete pet
If you're building a web app and don't want to deal with proxies, REST with JSON is simpler.
HTTP caching works beautifully with REST:
// Server response
HTTP/1.1 200 OK
Cache-Control: public, max-age=3600
ETag: "abc123"
// Client can cache and revalidate
fetch('https://api.petstore.com/pets/123', {
headers: {
'If-None-Match': 'abc123'
}
});
// Returns 304 Not Modified if unchanged
gRPC doesn't have built-in HTTP caching support.
gRPC excels in these scenarios:
When services talk to each other internally, gRPC's performance and type safety are invaluable:
// Order service calling inventory service
inventoryClient := pb.NewInventoryServiceClient(conn)
result, err := inventoryClient.CheckStock(ctx, &pb.StockRequest{
ProductId: orderedPet.Id,
Quantity: 1,
})
Server streaming makes real-time updates trivial:
// Live dashboard showing pet adoptions
stream, _ := client.StreamAdoptions(ctx, &pb.StreamRequest{})
for {
adoption, err := stream.Recv()
if err == io.EOF {
break
}
updateDashboard(adoption)
}
Mobile apps benefit from gRPC's efficiency. Smaller payloads mean less data usage and faster load times:
// iOS app using gRPC
let client = PetServiceClient(address: "api.petstore.com:443")
let request = ListPetsRequest.with {
$0.page = 1
$0.pageSize = 20
}
let call = client.listPets(request)
call.response.whenSuccess { response in
print("Loaded \(response.pets.count) pets")
}
When you have services in multiple languages, protobuf definitions ensure consistency:
# Generate code for all your services
protoc --go_out=./go-service petstore.proto
protoc --python_out=./python-service petstore.proto
protoc --java_out=./java-service petstore.proto
If you're considering migrating an existing REST API to gRPC, here's a practical approach:
Don't do a big-bang migration. Run REST and gRPC side by side:
package main
import (
"log"
"net"
"net/http"
"google.golang.org/grpc"
pb "github.com/yourorg/petstore/proto"
)
func main() {
// Start gRPC server
go func() {
lis, err := net.Listen("tcp", ":50051")
if err != nil {
log.Fatalf("Failed to listen: %v", err)
}
grpcServer := grpc.NewServer()
pb.RegisterPetServiceServer(grpcServer, &petServiceServer{})
log.Println("gRPC server listening on :50051")
grpcServer.Serve(lis)
}()
// Keep REST server running
http.HandleFunc("/api/pets", handlePets)
http.HandleFunc("/api/pets/", handlePet)
log.Println("REST server listening on :8080")
http.ListenAndServe(":8080", nil)
}
Start with service-to-service communication:
// Before: REST call between services
resp, err := http.Get("http://inventory-service/api/stock/123")
// After: gRPC call
stock, err := inventoryClient.GetStock(ctx, &pb.GetStockRequest{
ProductId: 123,
})
gRPC-Gateway generates a REST proxy from your protobuf definitions:
import "google/api/annotations.proto";
service PetService {
rpc GetPet(GetPetRequest) returns (Pet) {
option (google.api.http) = {
get: "/v1/pets/{id}"
};
}
rpc CreatePet(CreatePetRequest) returns (Pet) {
option (google.api.http) = {
post: "/v1/pets"
body: "*"
};
}
}
This generates a REST API automatically from your gRPC service. Clients can use either protocol.
Track metrics for both APIs:
import (
"github.com/prometheus/client_golang/prometheus"
"github.com/prometheus/client_golang/prometheus/promauto"
)
var (
restRequests = promauto.NewCounterVec(
prometheus.CounterOpts{
Name: "rest_requests_total",
},
[]string{"endpoint", "method"},
)
grpcRequests = promauto.NewCounterVec(
prometheus.CounterOpts{
Name: "grpc_requests_total",
},
[]string{"method"},
)
)
There's no universal winner. Choose based on your needs:
Use REST when:- Building public APIs for third-party developers - Simplicity and accessibility matter most - You need HTTP caching - Your team is more comfortable with REST
Use gRPC when:- Building internal microservices - Performance is critical - You need real-time streaming - Type safety and code generation add value - You're in a polyglot environment
Many successful companies use both. They expose REST APIs publicly while using gRPC internally for service-to-service communication.
The key is understanding the tradeoffs and choosing the right tool for each job. REST and gRPC aren't competitors—they're complementary tools in your API toolkit.
