REST vs. GraphQL: The Two-Minute Version You Actually Need

Every API discussion eventually summons the REST vs. GraphQL debate. Developers have opinions about this the way people have opinions about text editors — strongly held, identity-adjacent, and mostly irrelevant to the person who just wants to get data from point A to point B. As a non-developer working with APIs, you need to know roughly two things: what the difference is, and which one you're looking at. This article provides exactly that level of understanding — enough to work with either, not enough to start an argument on Hacker News.

What The Docs Say

REST — Representational State Transfer — is a set of conventions for organizing APIs around resources and standard HTTP methods. In a REST API, each type of data lives at its own URL. Want users? Hit GET /users. Want a specific user? GET /users/123. Want their posts? GET /users/123/posts. Each endpoint returns a fixed payload — all the fields that endpoint is configured to return. You can't pick and choose. You get the whole thing, every time.

GraphQL — developed by Facebook and released publicly in 2015 — takes a different approach. Instead of many endpoints that each return a fixed set of data, GraphQL gives you one endpoint. You send a query that describes exactly what data you want, and you get back exactly that — nothing more, nothing less. The query syntax uses curly braces and looks like a description of the data shape you want:

{
  user(id: 123) {
    name
    email
    posts {
      title
    }
  }
}

That query says: give me user 123's name and email, plus the title of each of their posts. You don't get their address, their phone number, their account creation date — just the fields you asked for. In REST, you'd potentially need two requests (one for the user, one for their posts) and both responses would include every field whether you wanted it or not.

The documentation for a REST API will show you a list of endpoints with their methods and response schemas. The documentation for a GraphQL API will show you the schema — the full catalog of types, fields, and relationships available — plus a query explorer (often called GraphiQL or Apollo Explorer) where you can build and test queries interactively.

What Actually Happens

The way to tell which kind of API you're dealing with is simple. If the docs show different URLs for different data — GET /posts, GET /comments, GET /users/{id} — it's REST. If the docs show a single endpoint (usually /graphql) and a query language where you describe what you want using nested curly braces — it's GraphQL. In practice, you'll know within ten seconds of looking at the documentation.

Most APIs you'll encounter as a non-developer are REST. Ghost's API is REST. Stripe is REST. OpenAI is REST. Twitter/X is REST. Nearly every SaaS product with an API uses REST conventions. This is the default, and it's the format covered in the rest of this series.

GraphQL shows up at GitHub (their v4 API), Shopify (their Storefront and Admin APIs), and some newer platforms that handle complex, nested data relationships. If you're building Shopify integrations or working with GitHub's API, you'll encounter GraphQL. Otherwise, you probably won't — at least not directly.

The practical difference comes down to data efficiency vs. query complexity. REST is simpler — you call a URL, you get data. The tradeoff is that you might get more data than you need (called over-fetching), or you might need multiple requests to assemble the data you want from different endpoints (called under-fetching). GraphQL solves both problems — one request, exactly the data you need — but the query syntax is more complex than "just call a URL." There's a learning curve, and for simple use cases, that curve isn't worth climbing.

Here's a concrete example of the over-fetching problem. You want to display a user's name on a dashboard. The REST endpoint GET /users/123 returns name, email, address, phone, company, website, and 15 other fields. You only needed the name. You just transferred and processed a bunch of data you'll never use. In GraphQL, you'd query { user(id: 123) { name } } and get back exactly { "name": "Jane Doe" }. For a single call, the efficiency difference is negligible. For an application making thousands of calls, it adds up.

The under-fetching problem is arguably more annoying in practice. You want a user and all their posts. REST might require two calls — GET /users/123 and GET /users/123/posts — because the user endpoint doesn't include posts. GraphQL gets both in one query. Again, for a simple workflow this barely matters. For complex data needs, it matters a lot.

When To Use This

You need this mental model when you're reading API documentation and the format doesn't look like what you're used to. If you've been working with REST APIs and suddenly encounter a Shopify GraphQL endpoint, knowing what you're looking at saves you from confusion. The query syntax is different, the request structure is different (GraphQL queries are typically sent as POST requests with the query in the request body), and the response structure mirrors the query structure rather than following a fixed schema.

For automation tools, the distinction is mostly handled for you. Zapier and n8n's native integrations abstract away whether the underlying API is REST or GraphQL — the node works the same way regardless. But when you use an HTTP Request node to call an API directly, you need to know which protocol you're dealing with so you can structure your request correctly.

The one GraphQL advantage worth remembering: if an API offers GraphQL and you're making direct API calls, you can request only the fields you need. This means smaller responses, less data to parse, and simpler extraction in your automation workflow. For APIs with large, complex response objects — Shopify product data, for example, which can include dozens of fields per product — this is genuinely useful.

If you're curious about GraphQL and want to explore it, GitHub's GraphQL API Explorer (available at developer.github.com) is the best playground. It has autocomplete, documentation built into the interface, and real data to query. Thirty minutes there will give you a working understanding of the syntax [VERIFY — confirm GitHub Explorer is still publicly accessible at this URL].

When To Skip This

If you're working exclusively with REST APIs — which, statistically, you probably are — you don't need to learn GraphQL. It's a tool for specific use cases, not a universal upgrade. The REST mental model (call a URL, get data back) covers the vast majority of APIs you'll encounter in automation work.

Don't let anyone convince you that GraphQL is "better" in some absolute sense. It's a different set of tradeoffs. REST is simpler to understand, simpler to call, and simpler to debug. GraphQL is more efficient for complex data needs and reduces the number of round trips. If you're building a mobile app that needs to minimize data transfer — GraphQL might be the right call. If you're connecting two SaaS tools in an n8n workflow — REST is fine. It's almost always fine.

The real skill here isn't knowing GraphQL syntax — it's recognizing which protocol you're looking at so you can read the documentation correctly. REST docs show endpoints. GraphQL docs show schemas and query builders. Once you know which one you're dealing with, the documentation tells you everything else.

This is part of CustomClanker's API Literacy series — the thing nobody explains before you try to connect two tools.