API Design: REST, GraphQL, and gRPC

Two Dissertations That Shaped the Internet

The year is 2000. Roy Fielding, a principal author of the HTTP specification, submits his PhD dissertation at UC Irvine. In Chapter 5, he describes an architectural style he calls Representational State Transfer REST. It is not a protocol or a standard; it is a set of constraints for designing networked applications. Within a decade, virtually every public API on the internet would claim to follow it.

Fifteen years later, Facebook engineers are building the first version of their mobile app. They face a concrete problem: the REST API designed for the website returns far too much data for a slow mobile network, while simultaneously forcing the mobile app to make five separate API calls to render a single screen. In 2015, they open source their solution: GraphQL. A year after that, Google open sources gRPC, designed for the high performance, strongly typed communication between their internal services.

Three different problems. Three different solutions. All three are production critical tools that every engineer must understand.

REST: The Architecture of the Web

REST is built on six constraints that, when followed, give you a scalable, simple, and cacheable API.

The six REST constraints:

1. Uniform Interface: Resources are identified by URLs. Interactions happen through representations (JSON, XML).
2. Stateless: Each request contains all information needed to process it. The server holds no client session state.
3. Cacheable: Responses must indicate whether they can be cached, enabling clients and intermediaries to cache responses.
4. Client Server: The client and server are separate, evolving independently.
5. Layered System: The client does not know if it is talking to the real server or a proxy, load balancer, or cache.
6. Code on Demand (optional): Servers can send executable code to clients (e.g., JavaScript).

HTTP Methods and What They Mean:

Idempotency is critical: making the same PUT or DELETE request 10 times has the same effect as making it once. POST is not idempotent posting the same order 10 times creates 10 orders.

Essential HTTP Status Codes:

REST API Best Practices:

• Version APIs in the URL: /v1/users, /v2/users
• Use nouns for resources, not verbs: /users/42 not /getUser?id=42
• Use cursor based pagination for large datasets (not offset/limit, which has race conditions)
• Document with OpenAPI/Swagger a machine readable specification that auto generates client SDKs and documentation

GraphQL: Ask Only for What You Need

Facebook's mobile app in 2012 had a concrete problem with REST:

• Over fetching: A REST endpoint for /users/42 returns 30 fields (address, preferences, billing info, etc.) but the mobile screen only needs 3 (name, avatar, bio). All that extra data wastes bandwidth on a slow mobile connection.
• Under fetching: To show a profile page, the app needs user data, their recent posts, and their follower count three separate REST requests, three round trips, three times the latency.

GraphQL solves both problems with a single endpoint. The client describes exactly what data it needs in a query, and the server returns exactly that nothing more, nothing less.

GraphQL concepts:

• Schema: Strongly typed definition of all data and operations available.
• Query: Read data. Like SELECT in SQL.
• Mutation: Write data. Like INSERT/UPDATE/DELETE.
• Subscription: Real time updates over a persistent connection.
• Resolver: The server side function that fetches data for each field.

The N+1 Problem: If you query 100 users and their posts, a naive GraphQL implementation runs 1 query for users and then 100 separate queries for their posts 101 queries total. The DataLoader library, also developed by Facebook, solves this by batching and caching per request database calls.

GraphQL is used by: GitHub (their public v4 API is GraphQL), Shopify, Twitter, Airbnb.

gRPC: Binary Speed for Internal Services

In 2016, Google open sourced gRPC the protocol they use internally across their data centres. It is built on two technologies:

1. HTTP/2: Multiplexed requests (multiple requests over one connection), header compression, bidirectional streaming.
2. Protocol Buffers (Protobuf): A binary serialisation format defined by a .proto schema file.

A REST+JSON response for a user object might be 240 bytes of human readable text. The same data as Protobuf binary is about 30 bytes 8× smaller. Smaller payloads mean faster transmission and less CPU spent on serialisation/deserialisation.

From a .proto file, gRPC auto generates client and server code in Go, Java, Python, C++, Node.js, and other languages. Type errors are caught at compile time, not at runtime.

gRPC streaming modes:

• Unary: Traditional request/response.
• Server streaming: One request, stream of responses (e.g., stock price updates).
• Client streaming: Stream of requests, one response (e.g., uploading a large file in chunks).
• Bidirectional streaming: Both sides stream simultaneously (e.g., real time collaboration).

gRPC is used by: Google internally, Netflix, Dropbox, Square. Kubernetes uses gRPC for all its internal API communication.

API Gateway Architecture

In a real system, different services may use different API styles. The API gateway provides a single entry point and handles cross cutting concerns for all of them.

API Security

JWT (JSON Web Tokens): After login, the server issues a signed token containing the user's ID and permissions. The client sends this token with every request. The server verifies the signature without a database lookup. JWT tokens must have an expiration time (exp claim) they are bearer tokens and can be stolen.

OAuth 2.0: The standard for delegated authorisation. When you log into a third party app with "Login with Google," you are using OAuth. The third party app gets a token scoped to specific permissions (read contacts, for example) without ever seeing your Google password.

API Keys: Simple secret strings sent in headers. Easy to implement, hard to rotate. Suitable for server to server communication where the client is a trusted service.

Rate Limiting: Every public API must limit how many requests a client can make. Common algorithms: Token Bucket (smooth rate limiting), Leaky Bucket (constant output rate), Sliding Window (accurate count over rolling time window). GitHub's API allows 5,000 requests per hour per authenticated user.

REST vs GraphQL vs gRPC

Choosing the Right API Style

• Public API for third party developers? Use REST. It is universally understood, easily documented with OpenAPI, and every language has HTTP clients.
• Mobile app with complex data needs? Use GraphQL. Query exactly what the screen needs in one round trip.
• Internal microservice communication? Use gRPC. The performance and type safety advantages compound at scale.
• Real time features? Use GraphQL subscriptions for client facing real time, or gRPC bidirectional streaming for internal.

Key Takeaways

Roy Fielding's 2000 dissertation did not invent the web it described why the web worked so well and gave engineers a vocabulary for replicating that success. Facebook's GraphQL in 2015 did not invalidate REST it solved a specific problem (mobile bandwidth and round trips) that REST was not designed to address. Google's gRPC solved a different problem entirely: making cross service communication inside a data centre as fast and safe as a function call.

The professional answer to "which API technology should we use?" is never a single technology. It is: REST for public facing APIs, GraphQL where flexible queries are needed, and gRPC where raw performance matters inside your infrastructure.