An API is a promise. Once a mobile app, a partner company, or another team's service depends on your endpoint, changing it carelessly breaks their software. A well-designed API is easy to understand, hard to misuse, efficient over the network, and able to evolve without breaking clients.
In the Client-Server Architecture & APIs chapter we saw what an API is and how a request travels from client to server. This chapter goes one level deeper and compares the three API styles you will meet most often in system design: REST, GraphQL and gRPC. Each has a working, runnable example, followed by the design rules (idempotency, pagination, versioning, errors) that matter whichever style you choose.
REST GET /students/21/courses many URLs, one per resource, JSON over HTTP
GraphQL POST /graphql { student(roll:21) { name courses { title } } }
one URL, client chooses the fields
gRPC ResultService.GetResult(roll=21) call a typed method, Protobuf over HTTP/2
REST
REST (Representational State Transfer) is an architectural style, described by Roy Fielding in his 2000 doctoral dissertation, in which a server exposes resources identified by URLs, and clients manipulate them through a uniform interface: the standard HTTP methods.
Fielding's constraints include: client-server separation, statelessness (each request carries everything needed to process it, so any server can handle it, which is what makes load balancing easy), cacheability, a uniform interface, and a layered system (proxies, CDNs and gateways can sit in between). In everyday use, "REST API" means "resource-oriented JSON over HTTP".
Resources are nouns, methods are verbs
Action | Good (resource-oriented) | Avoid (verbs in URL) |
|---|---|---|
List books |
|
|
Read one book |
|
|
Create |
|
|
Replace / partly update |
|
|
Delete |
|
|
A student's courses |
|
|
Safe and idempotent methods
These two properties, defined in the HTTP specification (RFC 9110), decide what is safe to retry, which is critical in a world of timeouts.
Safe: the method only reads; it does not change server state. Idempotent: sending the same request once or many times has the same effect on the server as sending it once.
Method | Typical use | Safe? | Idempotent? |
|---|---|---|---|
GET | Read | Yes | Yes |
HEAD / OPTIONS | Metadata / capabilities | Yes | Yes |
PUT | Create or replace at a known URL | No | Yes |
DELETE | Remove | No | Yes |
POST | Create in a collection, or trigger an action | No | No |
PATCH | Partial update | No | Not guaranteed (depends on the patch) |
Why is PUT idempotent but POST not? PUT /books/7 {title: "X"} sent three times still leaves one book 7 titled "X". POST /books {title: "X"} sent three times may create three books. Note that idempotency is about the server state, not the response: a second DELETE may answer 404 or 204, and that is fine.
Status codes that matter
Code | Meaning | When |
|---|---|---|
200 OK | Success with a body | Normal GET, PUT, PATCH |
201 Created | New resource made | POST; include a |
204 No Content | Success, no body | DELETE |
400 Bad Request | Malformed request | Invalid JSON, wrong types |
401 Unauthorized | Not authenticated | Missing or invalid token |
403 Forbidden | Authenticated but not allowed | Student tries to edit marks |
404 Not Found | No such resource | Unknown ID |
409 Conflict | Clashes with current state | Username taken, version mismatch |
422 Unprocessable Content | Well-formed but semantically invalid | Required field empty |
429 Too Many Requests | Rate limit hit | Covered later in the Rate Limiting chapter |
500 / 503 | Server error / temporarily unavailable | Bug / overload or maintenance |
For error bodies, a standard format exists: Problem Details for HTTP APIs (RFC 9457, which replaced RFC 7807), a JSON object with fields such as type, title, status and detail.
Making POST safe to retry: idempotency keys
A payment request times out. Did the charge happen? If the client retries a plain POST, the customer may pay twice. The common fix, popularised by payment APIs such as Stripe, is an idempotency key: the client generates a unique ID per logical operation and sends it in a header. The server stores the response for each key and, on a retry with the same key, returns the stored response instead of doing the work again. (An IETF draft standardising the Idempotency-Key header is in progress; it is not yet an RFC.)
Worked example: a small REST API
The program below starts a real HTTP server using only Python's standard library, then calls it as a client. Watch the status codes, the idempotent retry, and the double DELETE.
import json, threading, urllib.request, urllib.error
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
books = {1: {"id": 1, "title": "Operating System Concepts"}}
next_id = 2
seen_keys = {} # Idempotency-Key -> saved response
class BooksAPI(BaseHTTPRequestHandler):
def send(self, status, body=None, headers=()):
self.send_response(status)
for k, v in headers:
self.send_header(k, v)
data = json.dumps(body).encode() if body is not None else b""
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(data)))
self.end_headers()
self.wfile.write(data)
def book_id(self):
parts = self.path.strip("/").split("/") # ["books"] or ["books", "7"]
return int(parts[1]) if len(parts) == 2 and parts[1].isdigit() else None
def do_GET(self):
bid = self.book_id()
if self.path == "/books":
return self.send(200, list(books.values()))
if bid in books:
return self.send(200, books[bid])
self.send(404, {"error": "book not found"})
def do_POST(self):
global next_id
key = self.headers.get("Idempotency-Key")
if key in seen_keys: # retry of the same request
return self.send(*seen_keys[key])
body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
if not body.get("title"):
return self.send(422, {"error": "title is required"})
book = {"id": next_id, "title": body["title"]}
books[next_id] = book
next_id += 1
resp = (201, book, [("Location", f"/books/{book['id']}")])
if key:
seen_keys[key] = resp
self.send(*resp)
def do_DELETE(self):
books.pop(self.book_id(), None) # deleting twice is fine: idempotent
self.send(204)
def log_message(self, *args): # keep the output quiet
pass
def call(method, path, body=None, headers=None):
req = urllib.request.Request(f"http://127.0.0.1:{port}{path}", method=method,
data=json.dumps(body).encode() if body else None,
headers={"Content-Type": "application/json", **(headers or {})})
try:
with urllib.request.urlopen(req) as r:
status, text = r.status, r.read().decode()
except urllib.error.HTTPError as e:
status, text = e.code, e.read().decode()
print(f"{method:6} {path:9} -> {status} {text}".rstrip())
server = ThreadingHTTPServer(("127.0.0.1", 0), BooksAPI)
port = server.server_address[1]
threading.Thread(target=server.serve_forever, daemon=True).start()
call("GET", "/books/1")
call("GET", "/books/9")
call("POST", "/books", {"title": ""})
key = {"Idempotency-Key": "c0ffee-42"}
call("POST", "/books", {"title": "Computer Networks"}, key)
call("POST", "/books", {"title": "Computer Networks"}, key) # client retry
call("GET", "/books")
call("DELETE", "/books/2")
call("DELETE", "/books/2")
server.shutdown()
Output:
GET /books/1 -> 200 {"id": 1, "title": "Operating System Concepts"}
GET /books/9 -> 404 {"error": "book not found"}
POST /books -> 422 {"error": "title is required"}
POST /books -> 201 {"id": 2, "title": "Computer Networks"}
POST /books -> 201 {"id": 2, "title": "Computer Networks"}
GET /books -> 200 [{"id": 1, "title": "Operating System Concepts"}, {"id": 2, "title": "Computer Networks"}]
DELETE /books/2 -> 204
DELETE /books/2 -> 204
The empty title gets 422, not 500: the client's mistake, clearly reported.
The retried POST with the same
Idempotency-Keyreturns the same book 2; no duplicate is created.The second DELETE also returns 204, and the state is unchanged: idempotent.
Pagination
Never return an unbounded list. Two common styles:
Style | Request | Pros | Cons |
|---|---|---|---|
Offset |
| Simple; can jump to page N | Database still scans and skips the first 40 rows (slow for deep pages); if new posts arrive, items shift and the user sees duplicates or misses some |
Cursor (keyset) |
| Fast at any depth (uses an index: | Cannot jump to an arbitrary page |
Feeds and infinite scroll use cursors. The cursor is usually an opaque encoded value (here base64 of {"id":981}) so clients do not depend on its internals.
Versioning
In the URL:
/v1/books,/v2/books. Most common and most visible.In a header: for example
Accept: application/vnd.example.v2+jsonor a custom version header. Cleaner URLs, less visible.
Whatever you choose, prefer backward-compatible changes: adding a field or an endpoint does not need a new version; removing or renaming a field, or changing its type, does.
GraphQL
GraphQL is a query language for APIs and a runtime for executing those queries against a typed schema. The client sends a query describing exactly which fields it needs, usually to a single endpoint, and receives a JSON response with exactly that shape.
Facebook built GraphQL in 2012 for its mobile apps and open-sourced it in 2015; it is now governed by the GraphQL Foundation. The latest edition of the specification is the September 2025 edition, the first new edition since October 2021 (it standardised, among other things, "OneOf" input objects).
The problem it solves
A mobile "student card" screen needs a student's name and course titles. With REST that might be:
GET /students/21 → returns 25 fields; the screen uses 1 (over-fetching)
GET /students/21/courses → second round trip (under-fetching)
On a slow mobile network every extra round trip and every unused kilobyte hurts. GraphQL lets the client ask for exactly what the screen needs in one request.
Worked example: schema, resolvers and a query
This uses graphql-core, the Python port of the reference implementation. The schema defines types; resolvers are functions that fetch each field's data.
# pip install graphql-core
from graphql import build_schema, graphql_sync
schema = build_schema("""
type Query {
student(roll: Int!): Student
}
type Student {
roll: Int!
name: String!
cgpa: Float
courses: [Course!]!
}
type Course {
code: String!
title: String!
credits: Int!
}
""")
COURSES = {"CS301": ("Operating Systems", 4), "CS302": ("DBMS", 4), "CS303": ("Networks", 3)}
STUDENTS = {21: {"roll": 21, "name": "Asha", "cgpa": 8.7, "codes": ["CS301", "CS302"]}}
class Root: # resolvers: how to fetch each field
def student(self, info, roll):
s = STUDENTS.get(roll)
if s is None:
return None
return {**s, "courses": [{"code": c, "title": COURSES[c][0], "credits": COURSES[c][1]}
for c in s["codes"]]}
query = """
query StudentCard($roll: Int!) {
student(roll: $roll) {
name
courses { title }
}
}
"""
result = graphql_sync(schema, query, root_value=Root(), variable_values={"roll": 21})
print(result.data)
bad = graphql_sync(schema, "{ student(roll: 21) { name salary } }", root_value=Root())
print(bad.errors[0].message)
Output:
{'student': {'name': 'Asha', 'courses': [{'title': 'Operating Systems'}, {'title': 'DBMS'}]}}
Cannot query field 'salary' on type 'Student'.
The response contains only name and course titles, nothing more. The second query asks for a field that is not in the schema, and the server rejects it during validation, before running any resolver. The schema is a strongly typed contract that tools can use to generate client code and documentation.
Operations
Query: read data.
Mutation: change data, for example
mutation { enroll(roll: 21, code: "CS303") { ok } }.Subscription: receive updates pushed by the server, typically over WebSockets.
The costs of GraphQL
N + 1 queries: a query for 50 students and their courses can call the courses resolver 50 times, each hitting the database. The standard fix is batching with a DataLoader, which collects the 50 IDs and makes one query.
Harder HTTP caching: most requests are POSTs to one URL, so CDNs cannot cache by URL as they do with REST GETs. Teams use persisted queries (a hash sent with GET) and client-side caches.
Expensive queries: clients can write deeply nested queries. Servers must limit depth and complexity, and rate limit by query cost.
Error handling: a response can contain both partial
dataand anerrorslist, and many servers return HTTP 200 even when some fields failed, so monitoring must inspect the body.
gRPC
gRPC is a high-performance remote procedure call (RPC) framework, open-sourced by Google in 2015, in which a client calls methods on a remote service as if they were local functions. Services and messages are defined in Protocol Buffers (Protobuf), and calls travel over HTTP/2.
Step 1: define the contract in a .proto file
syntax = "proto3";
package exam.v1;
service ResultService {
// Unary RPC: one request, one response
rpc GetResult (ResultRequest) returns (Result);
// Server-streaming RPC: one request, a stream of responses
rpc ListToppers (ToppersRequest) returns (stream Result);
}
message ResultRequest {
int32 roll = 1;
}
message ToppersRequest {
int32 limit = 1;
}
message Result {
int32 roll = 1;
string name = 2;
double cgpa = 3;
}
The numbers (= 1, = 2) are field tags. On the wire, Protobuf sends the tag and a compact binary value, not the field name. That is why it is small and fast, and also why you must never reuse or change a tag number once clients exist; adding new fields with new tags is backward compatible.
Step 2: generate code, implement the server, call it
The protoc compiler generates client and server code in many languages from the same file, so a Go service and a Java service share one exact contract.
# pip install grpcio grpcio-tools
# python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. results.proto
from concurrent import futures
import grpc
import results_pb2 as pb
import results_pb2_grpc as rpc
DATA = {21: ("Asha", 8.7), 22: ("Ravi", 9.1), 23: ("Meena", 9.4)}
class ResultService(rpc.ResultServiceServicer):
def GetResult(self, request, context):
if request.roll not in DATA:
context.abort(grpc.StatusCode.NOT_FOUND, f"roll {request.roll} not found")
name, cgpa = DATA[request.roll]
return pb.Result(roll=request.roll, name=name, cgpa=cgpa)
def ListToppers(self, request, context):
ranked = sorted(DATA.items(), key=lambda kv: -kv[1][1])
for roll, (name, cgpa) in ranked[:request.limit]:
yield pb.Result(roll=roll, name=name, cgpa=cgpa) # sent one by one
server = grpc.server(futures.ThreadPoolExecutor(max_workers=4))
rpc.add_ResultServiceServicer_to_server(ResultService(), server)
port = server.add_insecure_port("127.0.0.1:0")
server.start()
with grpc.insecure_channel(f"127.0.0.1:{port}") as channel:
stub = rpc.ResultServiceStub(channel)
r = stub.GetResult(pb.ResultRequest(roll=22), timeout=2) # always set a deadline
print("unary :", r.name, r.cgpa)
for r in stub.ListToppers(pb.ToppersRequest(limit=2), timeout=2):
print("streamed :", r.roll, r.name, r.cgpa)
try:
stub.GetResult(pb.ResultRequest(roll=99), timeout=2)
except grpc.RpcError as e:
print("error :", e.code().name, "-", e.details())
msg = pb.Result(roll=22, name="Ravi", cgpa=9.1)
print("protobuf size:", len(msg.SerializeToString()), "bytes;",
"JSON size:", len('{"roll":22,"name":"Ravi","cgpa":9.1}'), "bytes")
server.stop(0)
Output:
unary : Ravi 9.1
streamed : 23 Meena 9.4
streamed : 22 Ravi 9.1
error : NOT_FOUND - roll 99 not found
protobuf size: 17 bytes; JSON size: 36 bytes
Observe:
The client calls
stub.GetResult(...)like a normal function, with full type information.ListToppersstreams results one at a time over a single HTTP/2 stream.Errors use gRPC status codes (
NOT_FOUND,UNAVAILABLE,DEADLINE_EXCEEDED...), not HTTP codes.Every call sets a deadline (
timeout=2). In a chain of services the deadline propagates, so downstream work stops when the original caller has given up.The same record is 17 bytes in Protobuf versus 36 bytes as compact JSON.
Four kinds of RPC
Kind | Shape | Example |
|---|---|---|
Unary | 1 request → 1 response | Get a result |
Server streaming | 1 request → stream of responses | Download a large report in chunks, live price feed |
Client streaming | stream of requests → 1 response | Upload sensor readings, get a summary |
Bidirectional streaming | both sides stream independently | Chat, real-time location exchange |
Limitations
Browsers cannot speak native gRPC directly (they do not expose the needed HTTP/2 control). Web apps use gRPC-Web through a proxy such as Envoy, or a REST/JSON gateway in front.
Binary payloads are not human-readable; you need tools (such as
grpcurl) to debug.Load balancing: HTTP/2 keeps one long-lived connection with many requests on it, so a simple connection-level (L4) load balancer sends everything from one client to one server. You need request-level (L7) balancing or client-side balancing (see Load Balancing; client-side balancing comes up again in the later API Gateway & Service Discovery chapter).
REST vs GraphQL vs gRPC
Aspect | REST | GraphQL | gRPC |
|---|---|---|---|
Model | Resources + HTTP methods | Typed graph; client-written queries | Service methods (RPC) |
Endpoint(s) | Many URLs | Usually one ( | One per method ( |
Payload | Usually JSON | JSON | Protobuf (binary) |
Transport | HTTP/1.1, HTTP/2 or HTTP/3 | Usually HTTP; WebSockets for subscriptions | HTTP/2 |
Contract | Optional (OpenAPI) | Required schema | Required .proto |
Fetching | Fixed responses; over/under-fetching possible | Exactly the requested fields | Fixed messages |
HTTP caching | Excellent (GET + CDN) | Harder | Not via HTTP caches |
Streaming | Limited (SSE, chunked) | Subscriptions | Built in, all four kinds |
Browser support | Native | Native | Needs gRPC-Web / proxy |
Best fit | Public APIs, CRUD, cacheable content | Rich UIs, mobile apps, many client types with different needs | Internal service-to-service calls, low latency, streaming |
A common real-world combination: gRPC between internal microservices, and REST or GraphQL at the edge for browsers, mobile apps and partners, often translated at an API gateway.
Design Checklist for Any API
Consistent naming: plural nouns, one casing style, predictable URLs or method names.
Idempotency for anything that may be retried; idempotency keys for creates and payments.
Pagination for every list; cursors for feeds.
Clear errors with correct status codes and a machine-readable body.
Authentication and authorisation on every endpoint (covered later in Authentication & Authorization: OAuth & JWT).
Rate limits to protect the service (covered later in Rate Limiting).
Backward-compatible evolution: add, do not rename or remove; version when you must break.
Timeouts and deadlines on the client side of every call.
Common Mistakes
Using GET to change data. Crawlers, prefetchers and caches assume GET is safe.
Returning 200 with
{"error": ...}for REST failures. Clients, proxies and monitoring rely on status codes.Blindly retrying POST without an idempotency key, causing double orders or double payments.
Offset pagination on huge or fast-changing tables.
Choosing GraphQL to "be modern" for a simple CRUD API, then fighting N+1 queries and caching.
Reusing a Protobuf field number for a different field, which silently corrupts data for old clients.
Interview Questions
Q1. Which HTTP methods are idempotent, and why does it matter?
GET, HEAD, OPTIONS, TRACE, PUT and DELETE are idempotent; POST is not, and PATCH is not guaranteed to be. It matters because networks time out: a client (or proxy) can safely retry an idempotent request without causing a second effect. For non-idempotent operations such as payments, use an idempotency key so the server can recognise and de-duplicate retries.
Q2. When would you choose GraphQL over REST?
When many different clients (web, Android, iOS, partner apps) need different subsets of related data, and over-fetching or many round trips are a real problem, especially on mobile networks. GraphQL lets each client request exactly its fields in one call, backed by a typed schema. REST is often better for simple CRUD, public APIs, and content that benefits from HTTP/CDN caching.
Q3. Why is gRPC popular for communication between microservices?
Compact binary Protobuf messages and HTTP/2 multiplexing give low latency and high throughput; the .proto contract generates typed clients and servers in many languages; it supports streaming in both directions; and it has built-in deadlines and status codes. Its weaknesses (no direct browser support, binary payloads) matter less inside a data centre.
Q4. Offset vs cursor pagination: which would you use for an Instagram-style feed?
Cursor pagination. New posts arrive constantly, so offsets shift and users see duplicates or miss posts; deep offsets are also slow because the database must skip rows. A cursor (for example "posts with id less than X") uses an index, stays fast at any depth and is stable under inserts. Infinite scroll does not need to jump to page N.
Q5. What does the N+1 problem in GraphQL mean and how is it fixed?
A query for a list of N parents with a nested field causes one query for the list plus one query per parent for the nested data: N+1 database calls. It is fixed by batching and caching per request with a DataLoader, which collects all the keys requested in one tick and fetches them with a single query.
Summary
REST: resources as URLs, HTTP methods as verbs, status codes for outcomes; stateless and cache-friendly. Know which methods are safe and idempotent.
GraphQL: one endpoint, a typed schema, clients request exactly the fields they need; watch for N+1 queries, caching and query cost.
gRPC: typed RPC with Protobuf over HTTP/2; fast, streaming, multi-language; best for internal service calls.
For any style: idempotency keys, cursor pagination, clear errors, backward-compatible evolution, auth, rate limits and deadlines.
REST for the open web, GraphQL for demanding clients, gRPC for services talking to services, and idempotency everywhere a retry can happen.