API Design — REST, gRPC & GraphQL

Notebook Summary#

Hand-copy this. Every line is derivable from the Detailed Notes in §2.

Detailed Study Notes#

A customer taps Pay, the screen freezes, and they tap it again. Two payments leave their account. Somewhere a backend service received the same intent twice and treated each as a fresh order. Nothing was hacked — the API just had no way to know the second request was the same as the first. That one gap explains why API design is a discipline and not an afterthought: the rules below exist to stop exactly these quiet, expensive mistakes.

2.1What an API actually is#

An API is the agreed way for two pieces of software to talk. In a system design, your product is a set of backend services — boxes on a diagram. None of them is useful alone; they have to exchange information. The interface that governs that exchange is the API (its full name, Application Programming Interface, is worth saying once and then forgetting).

The API pins down the parts of the conversation that both sides must agree on: how a request is sent, what the request body looks like, which data format carries it, and how the response comes back. Get the contract right and the two services never have to meet — they just honour the shape.

2.2What makes an API well-designed#

Six habits separate an API a stranger can use from one that generates support tickets.

Simple and consistent#

An endpoint should read the way a person expects. The verb belongs to HTTP, and the URL names the thing. GET /users/123 is right; GET /getUser?id=123 is wrong twice over — it repeats the verb (GET already means "get") and buries the identifier in a query parameter when it identifies a specific resource and belongs in the path.

Resource-based URLs#

URLs name nouns, not actions. The action is carried by the HTTP method, so the path is free to describe what you are acting on. Good: /users, /orders, /products. Avoid /getUser or /createOrder — the verb is redundant with GET and POST.

Where the API lives — the request path through a typical system-design template.

Scalable, secure, versioned#

Scalable means the API is built to handle growth: pagination for large result sets, caching, rate limiting, and load balancing. Secure means HTTPS on the wire plus two distinct checks — authentication ("who are you?") and authorization ("what are you allowed to touch?") — and input validation so a malformed body is rejected at the door, before it reaches business logic. Versioned means you can evolve without breaking anyone; more on that in §2.5.

2.3The four parts of a request#

Every request the client sends is assembled from four slots, and knowing which slot a value belongs in is half of good API design.

2.4Status codes — the server's one-word reply#

A status code is how the server tells the client, in a number, how the request went. The leading digit is the whole story; the rest is nuance.

2.5Versioning — changing without breaking#

Versioning lets an API evolve while existing clients keep working. Suppose clients already call /v1/users. A new business requirement forces the request or response shape to change. If you edit /v1 in place, every current caller that sends the old shape starts failing — a bad experience nobody asked for.

Instead you publish /v2/users alongside /v1, onboard new consumers onto v2, migrate the old ones on their own schedule, and only then retire v1.

2.6Idempotency — the double-click insurance#

A request is idempotent if repeating it leaves the system in the same final state as doing it once. GET /users/123 is idempotent — asking ten times returns the same user and changes nothing. The danger case is a payment: without protection, clicking Pay twice charges the customer twice.

The fix: an idempotency key#

The client generates a unique id — usually a UUID — for the operation and sends it in a header. The first time the server sees Idempotency-Key: abc-123, it processes the request and stores the result against that key. If the same key arrives again, the server recognises it and returns the stored response instead of processing a second time. The "memory" can live in a fast cache (Redis) or the database, depending on how durable it must be.

POST /payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: abc-123

{ "amount": 500, "currency": "INR" }

2.7Pagination — never ship the whole haystack#

Pagination returns a large result set in slices instead of one giant payload. The client asks for a window: GET /users?page=2&limit=20 means "the 20 records on page 2."

Think of an infinite feed — LinkedIn, Instagram. If you've been away for days there may be 500 new items waiting. Sending all 500 at once wastes bandwidth on content you'll never scroll to. Instead the server sends a page, and when you scroll to roughly 80% of it, it pulls the next page. You get a smooth feed; the system avoids paying to move data you'd never read.

2.8REST — the default style#

REST is a stateless, resource-oriented way for two applications to talk over HTTP. The interview one-liner: "REST is a stateless, resource-oriented API style built on top of HTTP." Data is usually exchanged as JSON.

It replaced SOAP, an older style that leaned on verbose XML — heavier on the wire and harder for a human to read. REST is lighter, simpler, and speaks the web's native vocabulary that every browser already understands.

The two REST pains#

Because a REST endpoint's response shape is fixed by its contract, you hit two mirror-image problems.

A third, separate cost: JSON payloads are larger than a binary format. These three complaints are exactly what the next two styles were invented to fix — GraphQL for the fetch problems, gRPC for the payload size.

2.9gRPC — call a remote function like a local one#

gRPC lets one service call a method on another service as if it were a local function. It's a high-performance framework from Google that runs on HTTP/2 and serialises data with Protocol Buffers (a compact binary format) instead of JSON. The design goal: smaller payloads and lower latency for large microservice systems where REST-plus-JSON became the bottleneck.

How it works, in order#

1. Define the service in a .proto file — this is the contract: service name, methods, request and response message shapes.
2. A compiler generates client and server code automatically — the client stub, a server base class, and message classes. No hand-written networking.
3. The client calls a method on the stub as if it were local (stub.add(req)).
4. The request is serialised into compact binary.
5. It travels over HTTP/2 — multiplexed (many requests share one connection), header-compressed, persistent.
6. The server deserialises, runs the real logic, serialises the response, and sends it back.
7. The client deserialises and uses the result.

service Calculator {
  rpc Add (AddRequest) returns (AddResponse);
}

message AddRequest {
  int32 num1 = 1;
  int32 num2 = 2;
}

message AddResponse {
  int32 result = 1;
}

2.10GraphQL — the client orders exactly what it wants#

GraphQL is a query language for APIs where the client specifies exactly which fields it needs. Instead of many fixed endpoints, the application usually exposes one endpoint, and the query itself describes the desired shape. The interview one-liner: "GraphQL lets clients request only the fields they need, eliminating over- and under-fetching." It was created at Facebook to solve precisely the two REST pains.

query {
  user(id: "123") {
    name
    email
  }
}

The server defines a schema (types and fields); the client sends a query; resolvers fetch just those fields from the right databases or services; the response contains only what was asked for — no over-fetch, and no second round trip to under-fetch.

2.11Choosing between the three#

There's no universally correct answer — the skill is justifying your pick out loud. State the advantages of what you chose; if you chose gRPC or GraphQL, first name the REST disadvantage it removes.

Use REST for public APIs and normal CRUD. Use gRPC when internal services talk frequently and latency matters. Use GraphQL when a client needs flexible, customised data from multiple sources in a single request. And note the practical point from the session: services don't only talk via these styles — a message queue like Kafka handles asynchronous, decoupled communication, and truly independent services may not talk at all.

2.12Interview & practice Q&A#

2.13Key takeaways#

• An API is a contract; design it around resources (nouns in the path, verbs as HTTP methods).
• Status codes: first digit tells the story — 2xx you're fine, 4xx your fault, 5xx server's fault.
• Idempotency = same request, same final state; reason from the state, use a key to make POST safe.
• Store the idempotency key before processing, or a failed write lets a retry double-charge.
• Version by publishing v2 beside v1; never rewrite a live contract in place.
• Paginate large results; ship pages, not the whole set.
• REST for public/CRUD, gRPC for fast internal microservices, GraphQL for client-chosen fields.
• gRPC is all-or-nothing — both ends must speak it, which is why REST stays the common tongue.

Microexercises#

Reading proves you recognise the ideas. These prove you can use them. Attempt each before opening the walkthrough.

3.1Exercise 1 — design the endpoints (build-it)#

GET    /payments/123

GET    /payments?page=3&limit=20

POST   /payments
Idempotency-Key: 5f2c-uuid

DELETE /payments/123

3.2Exercise 2 — spot the idempotency bug (diagnose-it)#

def handle_payment(key, amount):
    result = charge_card(amount)        # 1. process first
    save_idempotency(key, result)       # 2. then remember the key
    return result

def handle_payment(key, amount):
    existing = lookup_idempotency(key)  # already seen?
    if existing:
        return existing.result          # replay, don't re-charge

    reserve_idempotency(key)            # 1. remember BEFORE processing
    result = charge_card(amount)        # 2. then process
    save_idempotency_result(key, result)
    return result