REST in one paragraph
A REST API models the domain as resources (/invoices, /invoices/inv_123) and acts on them with standard HTTP methods: GET to read, POST to create, PUT or PATCH to update, DELETE to remove. Responses are usually JSON, success and failure travel as HTTP status codes, and the contract is commonly described in OpenAPI. Because it rides on plain HTTP, REST works with every language, browser, proxy and cache without special tooling.
GET /v1/customers/cus_42/invoices?limit=2
Accept: application/jsonGraphQL in one paragraph
GraphQL puts a single typed schema behind one endpoint. Clients send a query naming exactly the fields and nested relations they want, and the server returns data in the same shape. Writes are mutations, and subscriptions push updates. The schema is introspectable, which powers strong tooling such as autocompletion and code generation.
query {
customer(id: "cus_42") {
name
invoices(first: 2) { id total status }
}
}gRPC in one paragraph
gRPC defines services and messages in .proto files using Protocol Buffers, then generates client and server code for many languages. Calls look like local function calls, travel over HTTP/2 as compact binary messages, and support unary calls plus client, server and bidirectional streaming. Browsers cannot speak native gRPC directly, so web clients typically go through gRPC-Web and a proxy.
service Billing {
rpc GetInvoice (GetInvoiceRequest) returns (Invoice);
}
message Invoice {
string id = 1;
int64 total_minor = 2;
string currency = 3;
}Key differences side by side
- Data fetching. REST returns a fixed representation per endpoint, which can mean over-fetching or several round trips. GraphQL returns exactly what the query asks for in one request. gRPC returns the message type the method defines.
- Contract. REST contracts are optional and usually written in OpenAPI. GraphQL and gRPC require a schema; the server will not run without one.
- Transport and format. REST and GraphQL usually send JSON over HTTP/1.1 or HTTP/2. gRPC sends binary Protocol Buffers over HTTP/2, which is smaller on the wire and faster to parse.
- Caching. REST
GETrequests cache naturally in browsers, CDNs and proxies. GraphQL queries are usuallyPOSTrequests to one URL, so caching moves into the client or uses persisted queries. gRPC caching is generally left to the application. - Errors. REST uses HTTP status codes. GraphQL often returns
200with anerrorsarray alongside partial data. gRPC has its own set of status codes such asNOT_FOUNDandUNAVAILABLE. - Browser support. REST and GraphQL work from any browser. gRPC needs gRPC-Web or a translating gateway.
- Learning curve. REST is the most familiar. GraphQL adds schema design, resolvers and query cost control. gRPC adds Protocol Buffers, code generation and HTTP/2 infrastructure.
When to use which
Choose REST for public APIs and partner integrations, where the widest possible audience, simple debugging with any HTTP client, and HTTP caching matter most. It is the safest default when you do not know who your consumers will be.
Choose GraphQL when many different clients (web, iOS, Android, partners) need different slices of the same connected data, and round trips or over-fetching are a real cost. It works well as an aggregation layer in front of several backend services.
Choose gRPC for internal service-to-service communication where you control both ends, need low latency and high throughput, want streaming, or benefit from generated, strongly typed clients in several languages.
Each choice also brings operational work. A public GraphQL API needs query depth and cost limits so one expensive query cannot exhaust the server. A gRPC estate needs load balancers and proxies that understand HTTP/2, plus a shared repository of .proto files. A REST API needs discipline about consistency, because nothing in the style itself enforces it; see API design best practices.
Many organisations use all three: gRPC between internal services, GraphQL or a backend-for-frontend for their own apps, and REST for the public API. The decision is per boundary, not per company.
How each style handles change and versioning
Every API style faces the same problem: providers must evolve, and existing clients must keep working. The styles differ in what they give you to manage that.
REST
REST has no built-in mechanism, so providers choose a versioning strategy: a version in the URL path, a header, a query parameter or a date. Additive changes such as new optional fields can ship in place; removals and type changes need a new version. Retirement is signalled with Deprecation and Sunset headers, covered in how to deprecate an API. Structural changes can be caught with an OpenAPI diff in CI.
GraphQL
GraphQL encourages continuous evolution of a single, unversioned schema. You add new fields and types freely, mark old ones with the built-in @deprecated(reason: "...") directive, watch field-level usage until nobody queries them, then remove them. Because clients only receive fields they ask for, adding fields is safe. Removing or renaming a field, changing a type, or making an argument required is still breaking, and schema diff tools exist to flag these.
gRPC
Protocol Buffers were designed for compatibility. Every field has a number, and the number, not the name, is what goes on the wire. Adding a field with a new number is safe because old readers skip unknown fields. Changing a field number or an incompatible type breaks clients, and a deleted field's number should be marked reserved so it is never reused. Larger changes are usually published as a new package version, such as billing.v2, alongside the old one.
Verifying behavior, whatever the style
Spec and schema diffs catch structural problems cheaply. Behavioral problems need evidence from real calls: contract tests for what consumers say they rely on, and traffic replay testing for what they actually send. Replaying recorded requests against the old and new implementation and diffing full responses works the same way for a REST endpoint, a GraphQL query or a gRPC method, which makes it a useful common gate when an organisation runs all three.
Frequently asked questions
What is the difference between REST and GraphQL?
REST exposes multiple resource URLs that each return a fixed representation, while GraphQL exposes one endpoint and a typed schema that clients query for exactly the fields they need. REST relies on HTTP caching and status codes; GraphQL relies on its schema and returns errors in the response body.
Is gRPC faster than REST?
Usually, for service-to-service calls. gRPC sends compact binary Protocol Buffers over HTTP/2 with long-lived connections, which reduces payload size and parsing cost compared with JSON. The real difference depends on payloads, network and implementation, so measure for your workload.
Does GraphQL need versioning?
GraphQL APIs usually avoid explicit versions. Providers add fields freely, mark old fields with the @deprecated directive, monitor usage and remove fields once nobody queries them. Removing or changing an existing field is still a breaking change.