An API is a contract with strangers
Ishaan's startup, DukaanPay, offers a public API that lets small shops take payments and list their orders. Three thousand developers he has never met build on it: billing apps, accounting plug-ins, WhatsApp bots. (Ishaan, DukaanPay and every number here are made up for teaching.)
Publishing an API means making promises to strangers:
- This call will keep working.
- Repeating it won't charge anyone twice.
- Asking for page two won't skip or duplicate rows.
Most API design failures are broken promises of exactly those kinds, and Ishaan breaks each one once:
| Broken promise |
Idea it forces |
| "Which kind of API should we even build?" |
REST vs GraphQL vs gRPC |
| "My nightly export skipped 14 orders" |
Cursor pagination |
| "A shop's customer was charged twice after a timeout" |
Idempotency keys |
| "We renamed one field and 400 integrations broke" |
Versioning and evolution |
| "One customer's script sent 10,000 requests a second" |
A rate limiter, end to end |
| "A developer changed an ID in the URL and saw another shop's orders" |
Authentication, authorisation, RBAC/ABAC |
This guide extends Networking and APIs and gRPC in depth.
1. "Which kind of API?": REST, GraphQL or gRPC
| Style |
Shape |
Strength |
Weakness |
Reach for it when |
| REST over HTTP+JSON |
Resources and verbs |
Universal tooling, HTTP caching, easy to explore |
Over/under-fetching; many round trips for rich screens |
Public APIs, CRUD-heavy services |
| GraphQL |
Client asks for exactly the fields it wants from one endpoint |
Flexible clients, fewer round trips, typed schema |
Harder caching, query cost control, N+1 in resolvers |
Many client types (web, mobile) with varied needs |
| gRPC |
Typed contracts over HTTP/2 with binary encoding |
Fast, streaming, generated clients |
Browser support needs a proxy; not human-readable |
Internal service-to-service traffic |
Ishaan's choice: REST for the public API, because every developer already knows it, and gRPC between DukaanPay's own services. If he ever adds GraphQL, it needs guardrails:
You've reached the free preview of this post.
Subscribe to the Blogs plan (₹99/mo) — or use any Algomi Suite, Career, Investor, or Trader plan — to keep reading.
See plans
