gRPC — Opsalis Learn

What Is gRPC?

gRPC (gRPC Remote Procedure Calls) is a high-performance, open-source RPC framework originally developed by Google. Released in 2015, it is now a Cloud Native Computing Foundation (CNCF) project used by organizations ranging from Netflix and Square to the US Department of Defense. gRPC is designed for low-latency, high-throughput communication between services — especially in microservice architectures where services call each other millions of times per second.

gRPC uses Protocol Buffers (protobuf) as its interface definition language and serialization format. You define your service methods and message types in a .proto file, then use the protoc compiler to generate client and server code in your language of choice — Go, Java, Python, C++, Rust, Node.js, and many more. Protobuf messages are serialized into a compact binary format that is significantly smaller and faster to parse than JSON or XML.

Under the hood, gRPC runs on HTTP/2, which provides multiplexing (multiple concurrent requests over a single TCP connection), header compression, and bidirectional streaming. This means a gRPC client can send a stream of messages to the server while simultaneously receiving a stream of responses — all over one connection. Four communication patterns are supported: unary (one request, one response), server streaming (one request, stream of responses), client streaming (stream of requests, one response), and bidirectional streaming (both sides stream simultaneously).

gRPC also provides built-in support for deadlines/timeouts (clients specify how long they are willing to wait), cancellation (either side can abort an RPC), interceptors (middleware for logging, auth, metrics), and load balancing. These features, combined with binary serialization and HTTP/2, make gRPC the fastest mainstream RPC framework available — typically 5-10x faster than equivalent REST/JSON calls.

How gRPC Works with Opsalis

gRPC APIs are binary and require generated client code — but Opsalis consumers never need to deal with any of that. The handler bridges gRPC to a clean REST interface automatically.

Owner provides a .proto file. Upload your Protocol Buffer service definition via the handler dashboard. The handler parses all service definitions, RPC methods, and message types.
Handler loads the proto, creates a gRPC client, and invokes methods. When a consumer request arrives as JSON, the handler maps it to the appropriate gRPC method, serializes the request to protobuf, sends it over HTTP/2 to your gRPC server, and deserializes the protobuf response back to JSON.
Supports unary and server-streaming RPCs. For unary calls, the handler returns a single JSON response. For server-streaming calls, the handler collects the stream and returns the results as a JSON array.

Your gRPC server stays untouched. No REST gateway needed, no transcoding proxy. The handler speaks native gRPC to your server and translates to JSON/OpenAPI for consumers.

Demo API: USGS Earthquake Data

This demo uses USGS Earthquake data — over 24,000 significant earthquakes (magnitude 5.5 and above) recorded by the United States Geological Survey. Query by magnitude range, date range, geographic region, and depth. Stream results for large queries. A perfect dataset for demonstrating gRPC's strengths in high-throughput data retrieval and server-side streaming.

← Owner Guide

Code Example

Query earthquakes using grpcurl (unary)

# Unary call: get earthquakes above magnitude 7.0
grpcurl \
  -plaintext \
  -d '{ "minMagnitude": 7.0, "limit": 5 }' \
  localhost:4004 \
  earthquake.EarthquakeService/SearchQuakes

Response (JSON representation)

{
  "quakes": [
    {
      "id": "us7000abc1",
      "magnitude": 7.8,
      "location": "Southern Turkey",
      "latitude": 37.174,
      "longitude": 37.032,
      "depth": 10.0,
      "timestamp": "2023-02-06T01:17:34Z"
    },
    ...
  ]
}

Server-streaming: stream all M6+ quakes in a region

# Server streaming: results arrive one at a time
grpcurl \
  -plaintext \
  -d '{
    "minMagnitude": 6.0,
    "minLatitude": 30.0,
    "maxLatitude": 45.0,
    "minLongitude": 25.0,
    "maxLongitude": 45.0
  }' \
  localhost:4004 \
  earthquake.EarthquakeService/StreamQuakes

gRPC at a Glance

Concept	Details
Transport	HTTP/2 (mandatory)
Data format	Protocol Buffers (binary), JSON also possible
Spec format	.proto files (Protocol Buffer IDL)
Communication patterns	Unary, server streaming, client streaming, bidirectional
Code generation	Yes — protoc generates client/server stubs
Best for	Microservices, real-time systems, high-throughput data pipelines