gRPC vs REST, byte by byte

Each bar is one call: the request (with an authorization token, as most APIs need) and the response carrying an order with the chosen number of line items. Headers are blue-grey, framing amber, the body green. Choose a protocol to inspect every header field or the body bytes.

• Compare the first call with the second. HTTP/1.1 sends the same headers again; HTTP/2's HPACK has stored them and sends one-byte references.
• Switch from 1 item to 100. Headers stop mattering and the body decides: protobuf stays well under JSON.
• Inspect the gRPC body to see how protobuf lays out fields: a tag byte, then a varint or a length and the bytes.

The HPACK encoder produces byte-for-byte the same output as the Python hpack library when both always use Huffman coding (this page uses Huffman only when it is shorter, as Go and nghttp2 do), and the protobuf encoder matches Google's protobuf runtime for these messages.

REST (representational state transfer) is the architectural style Roy Fielding described in his 2000 dissertation; in everyday use, a "REST API" means resources at URLs, manipulated with HTTP methods, with bodies usually in JSON. gRPC is a remote procedure call framework released by Google in 2015: services and messages are declared in a .proto file, code generators produce typed clients and servers, and calls travel as HTTP/2 requests with Protocol Buffers bodies.

Comparisons often mix up three separate things: the transport (HTTP/1.1 or HTTP/2), the payload format (JSON or protobuf), and the programming model (resources or procedures). The simulator separates the first two by adding a middle case, REST over HTTP/2, which is what most REST APIs actually use today behind a modern load balancer or CDN.

Bytes per call, request plus response, for an order with 1, 10 or 100 line items, on the first call of a connection and on a later one:

An HTTP/1.1 request is text: a request line, then one Name: value line per header, each ending in CR LF, and the same headers again on every request. The request and response headers in this example come to 434 bytes per call, and authorization tokens make that larger in practice.

HTTP/2 sends headers in HEADERS frames, compressed with HPACK. Each field is either an index into a table, or a literal that may be added to the table. The static table holds 61 common fields such as :method GET and content-type (name only). The dynamic table, 4,096 bytes by default and separate for each direction, holds fields sent earlier on the connection. Strings can be Huffman-coded with a fixed code tuned to header text. Here the REST headers take 264 bytes on the first call and 11 bytes afterwards, and gRPC's take 278 and 12. HPACK replaced the DEFLATE compression that SPDY used for headers after the CRIME attack showed it could leak secrets such as cookies one character at a time; with HPACK an attacker's guess has to match an entire header value.

Protocol Buffers write each field as a tag, the field number shifted left three bits plus a wire type, followed by the value: a variable-length integer (7 bits per byte, high bit set if more bytes follow), or a length and that many bytes for strings and nested messages. Field names never appear, and proto3 omits fields equal to their default. The order body, raw and gzipped:

A gRPC call is an HTTP/2 POST to /package.Service/Method with content-type: application/grpc and te: trailers. Each message in either direction is a length-prefixed message: one byte saying whether it is compressed and four bytes of length, then the protobuf. The response starts with a HEADERS frame (:status 200), carries the messages in DATA frames, and ends with a second HEADERS frame of trailers holding grpc-status and, on error, grpc-message. A call that fails immediately can send a single "trailers-only" HEADERS frame. Deadlines travel as grpc-timeout, for example 1S, so every server along the way knows how long the caller will wait.

REST reports outcomes with HTTP status codes. gRPC uses its own 17 codes in the trailer, from 0 (OK) to 16 (UNAUTHENTICATED), and usually sends HTTP 200 even for errors. If a gRPC client gets a response without grpc-status, for instance an error page from a proxy, it falls back to the mapping in the gRPC documentation:

• REST with JSON suits public APIs and browsers: every language and tool speaks it, responses are readable with curl, and HTTP caching, CDNs and proxies understand it.
• gRPC suits service-to-service calls inside a system you control: a typed contract with generated clients, streaming, deadlines that propagate, smaller payloads and cheaper parsing. It needs HTTP/2 end to end, a proxy for browsers, and tooling to read binary payloads.

Many systems use both, often generating the REST API from the same .proto files with gRPC-JSON transcoding.

Roy Fielding defined REST in his 2000 doctoral dissertation, drawing on his work on HTTP/1.1. Google developed Protocol Buffers internally from 2001 and open-sourced them in 2008, and used an RPC system called Stubby between its services. HTTP/2 was standardized in 2015 (RFC 7540, revised as RFC 9113 in 2022) along with HPACK (RFC 7541), and Google released gRPC the same year as an open successor to Stubby built on it. gRPC joined the Cloud Native Computing Foundation in 2017.