GraphQL Basics – Querying APIs the Modern Way

Note: This article was originally published on November 15, 2017. Some information may be outdated.

GraphQL offers a single endpoint where clients send queries describing the exact fields they require.
The server returns a JSON object with that shape--no more, no less.

---

REST vs GraphQL

Typical REST flow

GET /users/42          → user object
GET /users/42/repos    → list of repos
GET /users/42/followers → list of followers

Multiple round‑trips fetch related data, often including fields the UI never shows.

GraphQL equivalent

{
  user(id: 42) {
    name
    repos(limit: 3) { name stars }
    followers(limit: 5) { name }
  }
}

One request gets everything, trimmed to what the UI needs.

---

Query structure

• Fields: properties you want returned.
• Arguments: refine results (limit, order).
• Fragments: reusable field sets.
• Variables: externalise arguments to avoid string interpolation.

Example with variables:

query($id: ID!) {
  user(id: $id) {
    name
    avatar
  }
}

Send { "id": 42 } in the request body under variables.

---

Try it yourself (GitHub API)

1. Create a personal token with read:user scope.
2. POST to https://api.github.com/graphql with header Authorization: bearer <token>.
3. Send the query above to fetch your profile fields.

---

Schema language

A server publishes types:

type User {
  id: ID!
  name: String!
  repos(limit: Int = 5): [Repo!]!
}

type Repo {
  id: ID!
  name: String!
  stars: Int!
}

type Query {
  user(id: ID!): User
}

The client introspects this schema to know which fields exist and their types.

---

Benefits for front‑end devs

• Exact data - smaller payloads, faster rendering.
• Single round‑trip - fewer spinners.
• Strong typing - tools like autocomplete and compile‑time checks.
• Versionless - add fields without breaking clients.

---

Building a simple schema (Node)

npm init -y
npm install graphql express express-graphql

const { graphqlHTTP } = require('express-graphql');
const { buildSchema } = require('graphql');
const express = require('express');

const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

const root = { hello: () => 'Hello GraphQL' };

express()
  .use('/graphql', graphqlHTTP({ schema, rootValue: root, graphiql: true }))
  .listen(4000);

Navigate to http://localhost:4000/graphql and run { hello }.

---

GraphQL gained traction in 2017 as teams realised its power to streamline data fetching and reduce boilerplate compared with traditional REST endpoints.

---

Originally published at letanure.dev