How to Call a GraphQL API — A Beginner's Tutorial

Published 2026-01-22 · 8 min read
GraphQL is "just one endpoint that takes JSON" — and once you internalise that, the rest is syntax. This walkthrough uses a free public GraphQL endpoint so you can paste every example into your terminal and see real responses.

The mental model in one sentence

GraphQL is a single POST endpoint that takes { "query": "..." } and returns { "data": { ... } }.

That's it. Everything else — schemas, resolvers, the GraphiQL IDE — is tooling around that one shape.

Try it in 30 seconds

curl -X POST https://demo.totalshiftleft.ai/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ users(page:1, limit:3){ items{ id name email } } }"}'

That's a complete GraphQL request. Three users, three fields each.

Use GraphiQL for exploration

Open /graphiql — it's an in-browser IDE with autocomplete and a clickable schema browser. The fastest way to learn an unfamiliar GraphQL API is to type { in GraphiQL and just press Ctrl+Space.

Queries vs mutations

Query = read. Mutation = write. Same shape, different keyword:

mutation {
  createUser(input: { name: "Ada Lovelace", email: "ada@example.com" }) {
    id name createdAt
  }
}

Variables — never inline user input

Building queries by string-concatenation is the GraphQL equivalent of SQL injection. Use variables:

POST /graphql
{
  "query": "query U($id: ID!){ user(id:$id){ name email } }",
  "variables": { "id": "1" }
}

From JavaScript

const res = await fetch('https://demo.totalshiftleft.ai/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: `query($page: Int!) { users(page: $page, limit: 5) { items { id name } } }`,
    variables: { page: 1 }
  })
});
const { data, errors } = await res.json();
if (errors) console.error(errors);
console.log(data.users.items);

Errors are not HTTP errors

A GraphQL response can return HTTP 200 with an errors array. Always check errors before assuming success — this trips up everyone coming from REST.

Authentication

Send a JWT exactly like REST — Authorization: Bearer .... Get one from /auth-api. Protected fields like me will then resolve.

Common pitfalls

• Over-fetching by habit. Only ask for the fields you need — that's the whole point.
• The N+1 myth. N+1 is a server problem, not a client one. As a client you don't cause it.
• Hard-coded query strings. Move queries into .graphql files and use a tool (urql, Apollo, graphql-request) for type safety.

Frequently asked questions

Do I need a GraphQL client library?

No. fetch / requests / curl is enough. Libraries help with caching and types, not capability.

Where is the schema?

GET /schema.graphql returns the full SDL. Or use the Docs panel inside /graphiql.

Other free public APIs in this sandbox

Topics: how to call a GraphQL API · GraphQL tutorial · learn GraphQL · GraphQL fetch example · GraphiQL tutorial · free GraphQL API for testing