APIs for Product Managers
REST vs. GraphQL vs. Webhooks: A Data-and-Use-Case Framework
Fig 3.2 — Three shapes of caller need, three tools
These are not competing religions. They solve different shaped problems, and the shape of your caller's need should decide which one you're arguing about.
REST | GraphQL | Webhooks | |
|---|---|---|---|
Model | Fixed endpoints, each returning a fixed shape | One flexible endpoint, caller specifies exactly what fields they want | The server pushes data to the caller when something happens, instead of the caller asking |
Best for | Simple, predictable resources; wide tooling support; easy caching | Complex, nested data where different callers need different slices, and over/under-fetching is a real cost | Real-time or event-driven use cases — "tell me the moment a payment succeeds," not "let me keep asking" |
Caller experience | May need several calls to assemble a full picture | One call, exactly the fields needed, less over-fetching | No polling needed, but the caller must run a reachable server to receive events |
Failure mode | Over-fetching (getting fields you don't need) or under-fetching (needing five calls to build one screen) | A single expensive query can accidentally load the whole database if not carefully limited | If the caller's endpoint is down when the event fires, without a retry/redelivery system, the event can be silently lost |
Learning curve for new developers | Low — everyone already understands URLs and HTTP verbs | Moderate — a new query language to learn | Low to build, but requires the caller to run infrastructure, which raises the bar to integrate at all |
THE QUESTION THAT RESOLVES MOST OF THESE DEBATES
Is the caller asking "give me this thing" (REST fits well), "give me this thing plus these three related things, but only these fields" (GraphQL earns its complexity), or "tell me the moment this thing happens" (webhooks, possibly alongside a REST API for everything else)? Most real products need more than one of these for different parts of their surface — the mistake is picking one ideologically and forcing every use case through it.
YOUR MOVE THIS WEEK
Take your last ten API-related feature requests or complaints. Sort them into "needed more flexible querying," "needed real-time notification instead of polling," and "neither, this was a REST problem." Whichever pile is biggest tells you where your next real investment should go.