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.