TL;DR: Representational state transfer (REST) APIs send readable text over the web and work in every browser, so they suit public APIs. The gRPC Remote Procedure Calls (gRPC) framework sends compact binary messages over version 2 of Hypertext Transfer Protocol (HTTP), so it suits busy internal services. Many systems use REST at the edge and gRPC inside, and our eSignature API uses REST.
You are designing a new API, and the team is split. One side wants REST because every developer knows it. The other side wants gRPC because the services behind the app call each other thousands of times a minute.
Both sides have a point. This guide explains how the two approaches work, where each one fits, and how to run them side by side.
What is a REST API?
REST is a style for building APIs around resources, each with its own web address. A client sends a request over HTTP and usually gets JavaScript Object Notation (JSON) back.
Think of a library catalog. Every book has a shelf address, and you ask for the book at that address. You can borrow it, return it or update its record with a small set of standard actions.
A REST API works the same way:
- Each resource has an address such as
/users/123. - Standard HTTP methods act on it:
GETreads,POSTcreates,PUTorPATCHupdates andDELETEremoves. - Each request carries everything the server needs, so the server keeps no session state.
- Status codes, headers and caching follow the HTTP rules every tool already understands.
What is gRPC?
gRPC is an open source framework for calling a method on another machine as if it were local code. It runs over HTTP/2 and uses Protocol Buffers for its messages.
Think of ordering from a numbered menu. You say “number 12, no onions”, and the kitchen knows exactly what you mean. Both sides share the menu, so the order stays short.
In gRPC, the menu is a .proto file. It lists the service, its methods and the shape of every message.
From that file, tools generate a client and a server in many languages. The gRPC documentation covers each language.
Why use gRPC instead of REST?
Teams pick gRPC for smaller messages, shared contracts and streaming between services. These gains matter most when services call each other often.
Here is why teams use gRPC:
- Binary Protocol Buffers messages carry field numbers instead of repeated field names.
- HTTP/2 lets many calls share one long-lived connection.
- The
.protocontract generates typed clients, so field mismatches show up at build time. - Four call types are built in: unary, server streaming, client streaming and bidirectional streaming.
The trade-off is reach. Browsers need extra help to call gRPC, and you cannot read a binary message by eye.
How do JSON and Protocol Buffers differ?
JSON is text that people can read, while Protocol Buffers are binary data that programs read. That one difference shapes debugging, message size and how strict the contract is.
| JSON (usual with REST) | Protocol Buffers (gRPC) | |
|---|---|---|
| Format | Readable text | Compact binary |
| Debugging | Read it in any log or browser | Needs a tool or the .proto file |
| Message size | Field names repeat in every message | Field numbers replace names |
| Schema | Optional, often an OpenAPI file | Required, the .proto file |
| Code generation | Optional | Standard part of the workflow |
The Protocol Buffers documentation explains the format and its language guides in full. Our guide to OpenAPI and REST APIs shows how a REST API can get a contract too.
gRPC vs REST: how do they compare?
REST favors reach and readability, and gRPC favors compact messages and streaming. The table sets the main differences side by side.
| Aspect | REST | gRPC |
|---|---|---|
| Transport | Usually HTTP/1.1, sometimes HTTP/2 | HTTP/2 |
| Message format | Text, usually JSON | Binary Protocol Buffers |
| API style | Resources, such as /orders/123 |
Methods, such as OrderService.CreateOrder |
| Streaming | Added with server-sent events or WebSockets | Built in, four call types |
| Browser support | Works in every browser | Needs gRPC-Web and a proxy |
| Testing tools | curl, Postman and any HTTP client | grpcurl and generated clients |
On HTTP/1.1, each connection handles one request at a time. HTTP/2 lets many requests share one connection, which suits the steady traffic between services.
What does the same call look like in REST and gRPC?
The examples below fetch one user. REST describes the call with an address and a method, and gRPC describes it in a contract file.
REST request and JSON response
The client asks for user 123 and gets readable JSON back:
GET /users/123 HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 123,
"name": "Alex",
"email": "alex@example.com",
"isActive": true
}
gRPC contract in user.proto
The contract defines a GetUser method and the messages it sends and returns:
syntax = "proto3";
service UserService {
rpc GetUser(GetUserRequest) returns (GetUserResponse);
}
message GetUserRequest { int64 id = 1; }
message GetUserResponse {
int64 id = 1;
string name = 2;
string email = 3;
bool is_active = 4;
}
The client calls GetUser like a local function. Field numbers such as name = 2 travel on the wire instead of the field names.
Does gRPC have less overhead than REST?
For busy internal traffic, gRPC often has less overhead per call. The real gap depends on your payloads, network and how many calls each task makes.
Two things lower the overhead. Binary messages are smaller than the same data in JSON, and HTTP/2 reuses one connection for many calls. A small REST API with light traffic may see little difference.
Measure your own traffic before you switch. Our gRPC performance guide walks through HTTP/2, deadlines and a working gRPC service. Microsoft also documents gRPC on its own web framework for teams that build on it.
When should you use REST, and when gRPC?
Choose by who calls the API and how much traffic it carries. Public callers point to REST, and busy service-to-service calls point to gRPC.
When does REST fit?
- You publish an API for outside developers who use many languages and tools.
- Browsers call the API directly, and you want no proxy layer.
- Most calls create, read, update or delete records.
- You want to test with curl and read responses in logs.
When does gRPC fit for internal services?
For gRPC vs REST internal services work, the shared contract and built-in streaming tip the choice toward gRPC. It fits these cases:
- Services inside your platform call each other at high volume.
- You need streaming, such as telemetry, live dashboards or device data.
- Teams write services in several languages and want one shared contract.
- You want typed clients generated from one
.protofile.
How do REST and gRPC work together?
Many systems use REST at the edge and gRPC inside. Outside callers send JSON, and your own services keep their gRPC contracts.
An API gateway or a backend for frontend (BFF) layer sits between the two. The gRPC-Gateway project can generate that layer from your .proto file. It turns JSON requests into gRPC calls.
Browsers that must call gRPC directly use gRPC-Web through a proxy, by default Envoy. It supports unary calls and server streaming, and client or bidirectional streaming is still missing. Our guide to async API architecture adds queues to this picture.
What good habits keep REST and gRPC APIs healthy?
Both styles last longer when you treat the contract as a promise to your callers. The habits differ a little for each one.
Habits for REST APIs
- Use clear, noun-based addresses such as
/orders/123. - Return the right HTTP status code for each result.
- Document the API in an OpenAPI file.
- Add caching where responses rarely change, and version the API.
Habits for gRPC APIs
- Never reuse a Protocol Buffers field number, even after you delete the field.
- Add new fields instead of changing existing ones.
- Set a deadline on every call, so a slow service cannot hang the caller.
- Add tracing and metrics for each method.
What mistakes should you avoid when choosing?
Most trouble comes from treating gRPC as a drop-in swap for REST. Watch for these five:
- Moving a public API to gRPC when callers expect JSON over HTTP.
- Planning browser access late, after the gRPC services are already built.
- Using streams where a simple request and response would do.
- Assuming every load balancer and proxy in your network handles HTTP/2 well.
- Mixing many API styles with no shared rules for reviewing contracts.
How does this apply 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.
Your internal services can talk over gRPC and still call our REST API to send documents for signature. When a signer finishes, we can notify your app through webhooks.
For questions about an endpoint, write to our support portal.
Which BoldSign API plan do you need, and what does it cost?
You can try every endpoint in a free API sandbox account. Live API sending, with webhooks and embedded signing, 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 and REST?
You now know how each style works and where each one fits. Pick your next step:
- Create a free API sandbox account and send a test document through our REST API.
- Request a demo to see how the API fits your services.
- Read our gRPC performance guide to build and run a small gRPC service.
Frequently asked questions
Does gRPC always cut response times compared with REST?
Not always. Binary messages and shared connections lower overhead, but payload size, network and server load also count. Measure your own traffic before you switch.
Can I call gRPC directly from the browser?
Not with standard gRPC. Browsers use gRPC-Web, which goes through a proxy such as Envoy and supports unary and server streaming calls.
Do I need Protocol Buffers to use gRPC?
In practice, yes. Protocol Buffers are the default format for gRPC contracts and messages, and most gRPC tools expect them.
Should I move all my REST APIs to gRPC?
Usually not. Move the internal calls that have clear speed or streaming needs, and keep REST for public and browser-facing APIs.
Can one service offer both REST and gRPC?
Yes. You can run gRPC between your services and put gRPC-Gateway in front. It generates a reverse proxy that turns JSON requests into gRPC calls.
Why use gRPC for internal services?
Internal services call each other often, so small binary messages and long-lived connections save time. A shared contract file also keeps every team's client and server in step.
Does REST work over HTTP/2?
Yes. REST is a design style rather than a transport, so a REST API can run over HTTP/1.1 or HTTP/2 when the server and client support it.
Does the BoldSign API use REST or gRPC?
The BoldSign API is a REST API that returns JSON. You can call it from any language and test it in a free API sandbox account.