Cheat sheet · Communication
API styles
The problem
One screen of a food-delivery app, "My orders", built with REST, then GraphQL, with gRPC between services. Where each style fetches too much or too little, and the habits every API needs: cursor pagination, versioning and idempotency keys.
What you learn
- Over-fetching, under-fetching and the N+1 calls they cause
- REST, GraphQL and gRPC: what each is good at, on the same feature
- Cursor pagination instead of
OFFSET, and a new version instead of a breaking change - An
Idempotency-Keythat makes a repeatedPOSTsafe
Diagram as code
The lesson's final design as text: paste it into Jira, GitLab, GitHub, Notion or your docs, where Mermaid renders by itself. There are D2 and PlantUML (Confluence, IntelliJ) versions too.
Mermaid: flowchart
flowchart LR
n_phone(["Phone app"])
n_api["REST API"]
n_db[("Database")]
n_gql["GraphQL server"]
n_pricing["Pricing service"]
n_phone --> n_api
n_api --> n_db
n_phone --> n_gql
n_gql --> n_db
n_gql --> n_pricingMermaid: request sequence
sequenceDiagram
participant n_phone as Phone app
participant n_api as REST API
participant n_gql as GraphQL server
participant n_db as Database
participant n_pricing as Pricing service
Note over n_phone,n_api: REST: one resource, one URL
n_phone->>n_api: GET /v1/orders?limit=20 HTTP/1.1
n_api-->>n_phone: HTTP/1.1 200 OK
Note over n_phone,n_api: Under-fetching: 1 + 20 calls
n_phone->>n_api: phone network log: 21 requests, 2.6 s
Note over n_phone,n_api: Let the client choose fields
n_phone->>n_api: GET /v1/orders?limit=20#38;fields=id,status#38;expand=restaurant HTTP/1.1
n_api-->>n_phone: HTTP/1.1 200 OK
Note over n_phone,n_gql: GraphQL: the client writes the query
n_phone->>n_gql: POST /graphql HTTP/1.1
n_gql-->>n_phone: HTTP/1.1 200 OK
Note over n_gql,n_db: The N+1 moved to the server
n_gql->>n_db: SELECT * FROM orders WHERE user_id = 'u_42' LIMIT 20#59;
Note over n_gql,n_db: Collect the IDs, ask once
n_gql->>n_db: SELECT id, name FROM restaurants
n_db-->>n_gql: 14 rows
Note over n_gql,n_pricing: gRPC between services
n_gql->>n_pricing: POST /pricing.v1.Pricing/Quote HTTP/2
n_pricing-->>n_gql: HTTP/2 200
Note over n_api,n_db: Page 2 repeats page 1
n_api->>n_db: SELECT id, created_at FROM orders
n_db-->>n_api: ord_962 #124; 2026-11-17 18:02
Note over n_phone,n_api: Cursor pagination in /v2
n_phone->>n_api: GET /v2/orders?limit=20#38;after=c_ord_962 HTTP/1.1
n_api-->>n_phone: HTTP/1.1 200 OK
Note over n_phone,n_api: The retry places a second order
n_phone-xn_api: POST /v1/orders HTTP/1.1
Note over n_phone,n_api: Idempotency-Key: the same answer for a repeat
n_phone->>n_api: POST /v1/orders HTTP/1.1
n_api-->>n_phone: HTTP/1.1 201 CreatedD2
direction: right
n_phone: "Phone app" {
shape: rectangle
}
n_api: "REST API" {
shape: rectangle
}
n_db: "Database" {
shape: cylinder
}
n_gql: "GraphQL server" {
shape: rectangle
}
n_pricing: "Pricing service" {
shape: rectangle
}
n_phone -> n_api
n_api -> n_db
n_phone -> n_gql
n_gql -> n_db
n_gql -> n_pricingPlantUML: request sequence
@startuml
participant "Phone app" as n_phone
participant "REST API" as n_api
participant "GraphQL server" as n_gql
database "Database" as n_db
participant "Pricing service" as n_pricing
note over n_phone, n_api : REST: one resource, one URL
n_phone -> n_api : GET /v1/orders?limit=20 HTTP/1.1
n_api --> n_phone : HTTP/1.1 200 OK
note over n_phone, n_api : Under-fetching: 1 + 20 calls
n_phone -> n_api : phone network log: 21 requests, 2.6 s
note over n_phone, n_api : Let the client choose fields
n_phone -> n_api : GET /v1/orders?limit=20&fields=id,status&expand=restaurant HTTP/1.1
n_api --> n_phone : HTTP/1.1 200 OK
note over n_phone, n_gql : GraphQL: the client writes the query
n_phone -> n_gql : POST /graphql HTTP/1.1
n_gql --> n_phone : HTTP/1.1 200 OK
note over n_gql, n_db : The N+1 moved to the server
n_gql -> n_db : SELECT * FROM orders WHERE user_id = 'u_42' LIMIT 20;
note over n_gql, n_db : Collect the IDs, ask once
n_gql -> n_db : SELECT id, name FROM restaurants
n_db --> n_gql : 14 rows
note over n_gql, n_pricing : gRPC between services
n_gql -> n_pricing : POST /pricing.v1.Pricing/Quote HTTP/2
n_pricing --> n_gql : HTTP/2 200
note over n_api, n_db : Page 2 repeats page 1
n_api -> n_db : SELECT id, created_at FROM orders
n_db --> n_api : ord_962 | 2026-11-17 18:02
note over n_phone, n_api : Cursor pagination in /v2
n_phone -> n_api : GET /v2/orders?limit=20&after=c_ord_962 HTTP/1.1
n_api --> n_phone : HTTP/1.1 200 OK
note over n_phone, n_api : The retry places a second order
n_phone ->x n_api : [lost] POST /v1/orders HTTP/1.1
note over n_phone, n_api : Idempotency-Key: the same answer for a repeat
n_phone -> n_api : POST /v1/orders HTTP/1.1
n_api --> n_phone : HTTP/1.1 201 Created
@endumlPlantUML: components
@startuml
left to right direction
agent "Phone app" as n_phone
component "REST API" as n_api
database "Database" as n_db
component "GraphQL server" as n_gql
component "Pricing service" as n_pricing
n_phone --> n_api
n_api --> n_db
n_phone --> n_gql
n_gql --> n_db
n_gql --> n_pricing
@endumlRecap
Five habits for APIs.
1) REST is simple and caches well, but watch for N+1 and fat responses. 2) GraphQL lets the client choose, but batch the resolvers and limit query cost. 3) gRPC fits calls between your own services. 4) Page by cursor and ship breaking changes as a new version. 5) Every POST that creates something accepts an Idempotency-Key.
Numbers: at the start and at the end
| Metric | Start | End |
|---|---|---|
| Calls per screen | 1 | 1 |
| Screen load | 180 ms | 210 ms |
| Data per screen | 0.1 MB | 0.0 MB |
| Double orders | 0/day | 0/day |
Steps
- Case REST: one resource, one URL
The "My orders" screen needs, for each of the last 20 orders, its status and the restaurant name.
- Problem Under-fetching: 1 + 20 calls
The name is missing, so the app fetches each restaurant separately: one call for the list and twenty more, one per order.
- Fix Let the client choose fields
The REST API learns two parameters:
fieldslists what to return andexpandembeds a related object. - Case GraphQL: the client writes the query
A GraphQL server describes all data as one typed schema.
- Problem The N+1 moved to the server
The phone makes one call, but the GraphQL server resolves
restaurantseparately for each order. - Fix Collect the IDs, ask once
The server now collects all the restaurant IDs a request needs and asks the database once with
IN (...). - Case gRPC between services
The screen also shows a delivery fee and time from the pricing service.
- Problem Page 2 repeats page 1
Older orders load as you scroll, with
OFFSET 20. - Fix Cursor pagination in
/v2The page now says where it ended, not how many rows to skip: "give me 20 orders after this one".
- Problem The retry places a second order
The user taps "Order".
- Fix
Idempotency-Key: the same answer for a repeatBefore the first try the app generates a random key and sends it with every repeat of this order.
- Recap Recap
Five habits for APIs.
Terms
- REST
- One URL per resource and standard HTTP methods. Simple and cache-friendly, but it can lead to over-fetching, under-fetching and N+1 calls.
- GraphQL
- The client writes which fields it needs in the query and gets them in one call. The N+1 moves to the server, so resolvers are batched and query cost is limited.
- gRPC
- A fast RPC protocol with a strict schema and a binary format. It fits internal calls between your own services.
- Cursor pagination
- The next page is requested with a cursor pointing at the last item seen, not with OFFSET. New items no longer cause repeats or gaps.
- Idempotency key
- A unique key the client sends with every create request. The server stores it and answers a repeat with the same response instead of creating a second order.