gRPC vs. REST: Definitions and Key Differences

Direct answer: gRPC is an open-source remote procedure call framework. A client calls a named method defined in a service contract, usually written in Protocol Buffers, and tooling generates typed client and server code. REST is an architectural style for client-server systems built around resources, representations and standardized HTTP interactions. A REST-style API commonly uses URLs, HTTP methods and JSON, but JSON and HTTP alone do not make an interface fully RESTful. gRPC documentation and MDN’s REST glossary describe the distinction.

There is no universal winner. Choose gRPC when generated contracts, coordinated service development and streaming are central. Choose a REST-style HTTP API when broad access through browsers and ordinary HTTP tools, resource-oriented URLs, HTTP semantics or intermediary compatibility matter. Measure representative workloads before making a performance claim.

What gRPC is

gRPC models an API as services and methods. You declare request and response messages in a .proto file, compile that definition with Protocol Buffers and a gRPC plugin, then call generated stubs from supported languages. The framework uses HTTP/2 and defines four interaction patterns: unary, server streaming, client streaming and bidirectional streaming. The official core concepts guide covers the lifecycle and generated interfaces.

A unary call resembles a conventional request and response. Streaming calls keep a connection open so one or both sides can exchange a sequence of messages. gRPC also supplies a formal RPC status model, metadata and deadline mechanisms. Payloads are normally compact Protocol Buffer messages rather than human-readable JSON.

A small gRPC contract

syntax = "proto3";

package users;

service UserDirectory {
  rpc GetUser (GetUserRequest) returns (User);
  rpc ListUsers (ListUsersRequest) returns (stream User);
}

message GetUserRequest {
  string id = 1;
}

message ListUsersRequest {
  int32 page_size = 1;
}

message User {
  string id = 1;
  string display_name = 2;
  string email = 3;
}

The contract names methods and fixes the message fields. A generated client can expose GetUser as a typed method, while a generated server interface tells the service author which methods to implement. Additive fields can generally be introduced without changing existing field numbers; schema evolution still requires a compatibility policy and careful rollout.

What REST means

Representational State Transfer (REST) is a set of architectural constraints, including separation of client and server, stateless requests, a uniform interface and resource representations. In everyday engineering, “REST API” often means an HTTP API whose URLs identify resources and whose methods express operations. That loose usage is common, so inspect the actual contract rather than relying on the label.

HTTP supplies standardized method semantics. GET /users/42 retrieves a representation, POST /users creates a subordinate resource, PUT replaces a known resource, PATCH applies a partial change and DELETE removes one. MDN’s method reference documents safety, idempotence and cacheability properties. JSON is conventional, not mandatory: an HTTP API may return JSON, XML, HTML, images or another media type.

A REST-style request

curl --fail --silent --show-error \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.example.com/users/42'

The URL and method are visible in logs and command-line tools. A response might be:

{
  "id": "42",
  "display_name": "Ada Lovelace",
  "email": "ada@example.com"
}

gRPC vs. REST: the key differences

Dimension	gRPC	REST-style HTTP API
Interaction model	Call a named service method such as GetUser.	Address a resource and apply an HTTP method such as GET or PATCH.
Contract	Usually a Protocol Buffer IDL with generated stubs and interfaces.	No required schema or generator; OpenAPI can add a contract and generated clients.
Payload	Protocol Buffer binary messages by default.	JSON is common, but any HTTP representation can be used.
Streaming	Unary, server, client and bidirectional streaming are framework features.	Streaming requires an HTTP design or extension; ordinary request-response is most common.
Browser access	Use gRPC-Web and its browser-facing deployment path; a browser cannot directly use every conventional gRPC setup. See the gRPC-Web guide.	Standard browser and HTTP libraries can usually call the endpoint, subject to CORS and authentication rules.
Inspection	Binary payloads are less convenient to read; reflection and schema-aware tools help.	Methods, URLs, headers and JSON are often easy to inspect directly.
Errors	Uses a defined RPC status model and metadata.	Uses HTTP status codes and response bodies.
Transport	Uses HTTP/2.	Can use HTTP/1.1 or HTTP/2, depending on deployment.

Runnable client examples

The examples below show the same “get user” operation through each style. Replace the host, credentials and generated module names with those from your service.

Python gRPC client

Generate Python bindings with the Protocol Buffers compiler and the gRPC Python plugin, then install grpcio. The generated files in this example are users_pb2.py and users_pb2_grpc.py.

import grpc
import users_pb2
import users_pb2_grpc


def main():
    credentials = grpc.ssl_channel_credentials()
    with grpc.secure_channel("api.example.com:443", credentials) as channel:
        stub = users_pb2_grpc.UserDirectoryStub(channel)
        response = stub.GetUser(
            users_pb2.GetUserRequest(id="42"),
            timeout=5,
            metadata=(("authorization", "Bearer YOUR_TOKEN"),),
        )
        print(response.id, response.display_name)


if __name__ == "__main__":
    main()

Set a deadline on every production call. Handle status errors such as unavailable, deadline exceeded and unauthenticated explicitly, and only retry operations that are safe under your service’s semantics.

REST with Python

import requests

response = requests.get(
    "https://api.example.com/users/42",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer YOUR_TOKEN",
    },
    timeout=(3.05, 10),
)
response.raise_for_status()
user = response.json()
print(user["id"], user["display_name"])

REST with Node.js

const res = await fetch('https://api.example.com/users/42', {
  headers: {
    accept: 'application/json',
    authorization: 'Bearer YOUR_TOKEN'
  },
  signal: AbortSignal.timeout(10000)
});

if (!res.ok) {
  throw new Error(`HTTP ${res.status}: ${await res.text()}`);
}
const user = await res.json();
console.log(user.id, user.display_name);

REST with cURL

curl --fail-with-body --retry 2 --retry-all-errors \
  --connect-timeout 3 --max-time 10 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.example.com/users/42'

When should you use gRPC instead of REST?

• Choose gRPC as a candidate for internal services when one organization controls both ends, schema coordination is practical and generated, language-specific clients reduce integration work.
• Choose gRPC for continuous data flow when server, client or bidirectional streaming is a primary requirement.
• Choose REST as a candidate for public integrations when consumers include browsers, scripts, command-line clients and teams using varied HTTP tooling.
• Choose REST for resource workflows when URLs, HTTP method semantics, gateways, caches and existing API conventions already describe the domain clearly.

These are decision axes, not hard rules. A service can expose REST externally and gRPC internally when the operational cost of two boundaries is justified. Document the translation, authentication and observability behavior so the two interfaces do not drift.

Browsers, gateways and intermediaries

Conventional gRPC clients speak the framework’s HTTP/2 protocol and generated wire format. Browser applications normally use gRPC-Web, which provides a browser-compatible client path and commonly includes a proxy or compatible server configuration. The distinction matters when planning CORS, load balancing, streaming support and authentication. REST-style HTTP endpoints can usually be called with fetch, but they still need correct CORS headers and a browser-safe authentication scheme.

Intermediaries also shape the choice. HTTP caches and API gateways understand standard methods and status codes well. gRPC-aware load balancers, proxies and observability tools are available, but verify HTTP/2 support, timeout propagation, maximum message sizes and streaming behavior in every hop.

Performance, reliability and cost

gRPC documentation positions the framework for efficient, low-latency distributed communication, but the research does not establish a workload-independent speed advantage. Serialization, payload size, compression, connection reuse, HTTP version, runtime, network distance, server implementation and caching can dominate the result. Benchmark your actual message shapes and concurrency.

1. Measure cold and warm connections separately.
2. Use representative payload sizes and realistic compression settings.
3. Record p50, p95 and p99 latency, throughput, CPU and memory.
4. Include retries, deadlines, connection failures and partial streams in failure tests.
5. Compare equivalent semantics: a paginated REST request is not equivalent to an unbounded streaming RPC.

Reliability comes from explicit policies in either style. Set deadlines, cap retries with exponential backoff and jitter, propagate correlation IDs, validate response sizes and make mutations idempotent where possible. For REST, use status codes and an error schema consistently. For gRPC, map status codes to actionable categories and preserve trailing metadata useful to operators.

Cost is primarily an infrastructure and engineering question: bandwidth, proxy capacity, serialization CPU, connection counts, observability and maintenance. Protocol choice can change those costs, but neither label supplies a universal price or savings percentage.

Common errors and fixes

Symptom	Likely cause	Fix
gRPC client reports UNAVAILABLE	Wrong port, TLS mismatch, unavailable proxy or HTTP/2 failure.	Check the authority and port, use matching secure or insecure channel settings, and verify HTTP/2 support at each proxy.
Calls hang until the process is killed	No deadline was supplied, or a stream is waiting indefinitely.	Set per-call deadlines, enforce server limits and close streams when the consumer is done.
Browser gRPC call fails before reaching the service	Conventional gRPC was used instead of gRPC-Web, or CORS/proxy configuration is missing.	Use the documented gRPC-Web client path and configure the required proxy, headers and CORS policy.
REST returns 415 Unsupported Media Type	The request body’s media type is absent or unsupported.	Send the API’s required Content-Type and encode the body accordingly.
REST returns 401 or 403	Missing, expired or insufficient credentials.	Refresh the token, send the expected scheme and verify scopes and audience.
REST returns 429	Rate limit exceeded.	Honor Retry-After, add bounded backoff and reduce concurrency.
Generated gRPC code does not compile	Compiler or plugin version differs from the runtime, or the package path is wrong.	Pin compatible tool versions, regenerate from the intended .proto files and check language package options.
Fields disappear after a schema update	Field numbers were reused or old clients cannot understand a breaking change.	Never reuse released field numbers; reserve removed numbers and follow a compatibility policy.

A practical way to inspect screenshots of API documentation

When reviewing a gRPC or REST integration guide, you may need repeatable screenshots of pages, code samples or a specific documentation element. A browser automation setup can launch a headless browser, wait for network idle, set a viewport, hide consent dialogs and save an image. That approach gives control, but it also means maintaining browser binaries, timeouts, selectors and cleanup rules.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP or PDF. It accepts cookie and consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing result.

Use the ScreenshotNeo API documentation for all options. The basic calls are:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

For documentation comparisons, relevant options include full-page capture with lazy images loaded, CSS selector element capture, dark mode, 12 device presets or a custom viewport, retina scale, custom CSS and JavaScript, click and wait conditions, blocked ads or resource types, custom headers and cookies, timezone and geolocation, transparent backgrounds, resizing and a cache TTL you choose. Async jobs, signed webhooks, bulk capture for up to 100 URLs, usage reporting and signed links support larger pipelines. An MCP server provides take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients.

There is a free plan with 1,000 screenshots per month and no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan. Create a free ScreenshotNeo account to try it.

FAQ

Is gRPC a REST API?

No. gRPC is a remote procedure call framework. REST is an architectural style. gRPC uses HTTP/2 as a transport, but that does not make its method-oriented contract REST.

Is gRPC faster than REST?

Not as a universal rule. Binary serialization and connection behavior may help a particular workload, while payload shape, runtime, network and caching can outweigh protocol differences. Benchmark equivalent operations.

Can a browser call gRPC directly?

Use gRPC-Web for browser clients. Conventional gRPC deployments require a different client and network path.

Does REST require JSON?

No. REST transfers resource representations, and HTTP APIs can use many media types. JSON is simply the most common convention for business APIs.

Can one system expose both?

Yes. Teams sometimes use REST at an external boundary and gRPC between internal services. Keep contracts, authentication, observability and compatibility rules explicit at the translation layer.