Art of Codeartofcode
Lesson 3 of 17

24. APIs and Idempotency

1
The picture to keep in your head
2
24.1 What is an API contract?
3
24.2 What are the main API styles?
4
24.3 How do you version an API?
5
24.4 How does pagination work (offset vs cursor)?
6
24.5 How should errors and status codes work?
7
24.6 How does API auth work, in one page?
8
24.7 What is the double-charge problem?
9
24.8 How do idempotency keys work?
10
24.9 How do you retry safely?
11
24.10 How do webhooks work?
12
Memory card and where the analogy breaks
13
Practice: five levels
14
Interview questions
15
Solutions
16
Sources
17
Code lab
24. APIs and Idempotency

24.2 What are the main API styles?

3 min read+10 XP

At the machine: Coins, card or phone all buy the same water. Each suits a different customer: coins work everywhere, cards are fast, phones do more.

In the system: Three styles you'll be asked about:

the same request for book 42 with its author in REST, gRPC and GraphQL.

Figure: REST for broad, cacheable APIs; gRPC between services; GraphQL for many screens with different needs.

24.2.1 REST

At the machine: Coins: understood by every machine, everywhere.

In the system: REST models your API as resources (nouns with URLs) and uses HTTP methods as the verbs:

MethodMeaningSafe?Idempotent?
GET /orders/881ReadYesYes
POST /ordersCreate (server picks the ID)NoNo
PUT /books/42Replace with this exact stateNoYes
PATCH /books/42Partial updateNoNot necessarily
DELETE /books/42RemoveNoYes

Safe means it doesn't change anything; idempotent means doing it twice has the same effect as once (HTTP semantics, RFC 9110). PUT /books/42 with the same body three times leaves one book 42. POST /orders three times creates three orders, which is why 24.7 exists.

REST over JSON is the default for public APIs and for web and mobile clients: every language and tool speaks it, GET responses can be cached by browsers and CDNs (Chapter 26), and it's easy to debug with a browser or curl.

24.2.2 gRPC

At the machine: A card: faster than counting coins, but the machine needs a card reader.

In the system: gRPC lets one service call another's functions as if they were local: Catalog.GetBook({id: 42}). You define services and messages in a .proto file; gRPC generates typed client and server code. Messages are encoded as compact binary Protocol Buffers and sent over HTTP/2, which supports many calls on one connection and streaming in both directions.

  • Good: fast, small messages, strict types, generated clients, streaming. Ideal between your own services.
  • Less good: browsers can't call it directly without a proxy (gRPC-Web), harder to inspect by eye, and less natural for public APIs.

24.2.3 GraphQL in brief

At the machine: A machine where you type exactly what you want: "water, and a pack of biscuits", and get both in one go.

In the system: GraphQL exposes one endpoint and a typed schema. The client sends a query describing exactly the fields it wants, possibly across related objects, and gets exactly that shape back in one round trip.

  • Good: no over-fetching (getting fields you don't need) or under-fetching (several calls for one screen). Great when many different screens or apps need different shapes of the same data.
  • Costs: harder HTTP caching (most queries are POSTs to one URL), a single query can be very expensive, so you need query cost limits, depth limits and careful data loading (to avoid the "N+1 queries" problem). Rate limiting by request count no longer makes sense.

In interviews: REST for public and simple APIs, gRPC for internal service-to-service, GraphQL when many clients need flexible shapes, and you can mix them.

Memory code: "Coins for everyone, cards between friends, a custom order for picky screens."