mufassall

Cheat sheet · Communication

API styles

12 min · Beginner · mufassall.dtwin.uz/en/l/apis/

← Open the lesson

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-Key that makes a repeated POST safe
Final scene
15%20%15%

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_pricing

Mermaid: 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 Created

D2

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_pricing

PlantUML: 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
@enduml

PlantUML: 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
@enduml

Recap

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

MetricStartEnd
Calls per screen11
Screen load180 ms210 ms
Data per screen0.1 MB0.0 MB
Double orders0/day0/day

Steps

  1. Case REST: one resource, one URL

    The "My orders" screen needs, for each of the last 20 orders, its status and the restaurant name.

  2. 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.

  3. Fix Let the client choose fields

    The REST API learns two parameters: fields lists what to return and expand embeds a related object.

  4. Case GraphQL: the client writes the query

    A GraphQL server describes all data as one typed schema.

  5. Problem The N+1 moved to the server

    The phone makes one call, but the GraphQL server resolves restaurant separately for each order.

  6. Fix Collect the IDs, ask once

    The server now collects all the restaurant IDs a request needs and asks the database once with IN (...).

  7. Case gRPC between services

    The screen also shows a delivery fee and time from the pricing service.

  8. Problem Page 2 repeats page 1

    Older orders load as you scroll, with OFFSET 20.

  9. Fix Cursor pagination in /v2

    The page now says where it ended, not how many rows to skip: "give me 20 orders after this one".

  10. Problem The retry places a second order

    The user taps "Order".

  11. Fix Idempotency-Key: the same answer for a repeat

    Before the first try the app generates a random key and sends it with every repeat of this order.

  12. 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.