Chapter 19 of 33

API Design: REST, GraphQL & gRPC

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

GET /books

GET /getAllBooks

Read one book

GET /books/7

GET /getBook?id=7

Create

POST /books

POST /createBook

Replace / partly update

PUT /books/7 / PATCH /books/7

POST /updateBook

Delete

DELETE /books/7

GET /deleteBook?id=7 (dangerous: crawlers follow GET links)

A student's courses

GET /students/21/courses

GET /studentCourses?s=21

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 Location header with its URL

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-Key returns 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

GET /posts?limit=20&offset=40

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)

GET /posts?limit=20&after=eyJpZCI6OTgxfQ==

Fast at any depth (uses an index: WHERE id < 981); stable when new items are inserted

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+json or 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 data and an errors list, 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.

  • ListToppers streams 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 (/graphql)

One per method (/package.Service/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.