What is GraphQL

In the previous lesson we sketched GraphQL in one sentence. Now let’s slow down and name the four ideas that make it work. Get these four straight and everything else in the course is a refinement of them.

Idea 1 — A single endpoint

A REST API tends to grow one URL per resource: a path for users, another for their posts, another for comments. A GraphQL API typically exposes one endpoint (conventionally /graphql) for all reads and writes. You do not navigate between URLs; you navigate between fields of a typed graph. The endpoint is fixed; what changes from request to request is the query you send to it.

Idea 2 — A typed schema is the contract

Every GraphQL API is defined by a schema written in the Schema Definition Language (SDL). The schema lists the types, the fields on each type, and what each field returns. It is the single source of truth that both client and server agree on:

type Author {
  name: String
  country: String
}

type Book {
  title: String
  year: Int
  author: Author
}

type Query {
  featuredBook: Book
}

Because the schema is typed and machine-readable, tools can validate queries before they ever run, autocomplete fields as you type, and generate TypeScript types automatically. The contract is enforced, not merely documented.

Idea 3 — Clients specify the query

A query is a selection of fields that mirrors the schema’s shape. The client decides which fields it wants and how deep to go. The server promises the response will have the same shape as the request.

flowchart LR
  Q["Query selection: featuredBook -> title, author -> name"] --> SRV["GraphQL server"]
  SRV --> RES["Response: featuredBook -> title, author -> name"]
  RES -.->|"same shape"| Q

The response mirrors the query — same fields, same nesting.

Idea 4 — No over-fetching, no under-fetching

These two failure modes drive much of GraphQL’s design:

Over-fetching — an endpoint returns more data than the screen needs, wasting bandwidth and forcing clients to ignore fields.
Under-fetching — an endpoint returns too little, so the client must make several follow-up requests to assemble one view.

Because a GraphQL client lists the exact fields it wants — across related types, in a single round trip — it sidesteps both. You ask for the title, the year, and the author’s name, and that is precisely what comes back.

See it select specific fields

Run the example below. The schema offers a featuredBook with many fields available, but the query deliberately asks for only a few. Watch the response contain only what was requested.

JavaScript

(async () => {
  const { graphql, buildSchema } = await import('https://esm.sh/graphql@16');

  const schema = buildSchema(`
    type Author {
      name: String
      country: String
    }
    type Book {
      title: String
      year: Int
      pages: Int
      author: Author
    }
    type Query {
      featuredBook: Book
    }
  `);

  const root = {
    featuredBook: () => ({
      title: 'The Typed Graph',
      year: 2024,
      pages: 312,
      author: { name: 'A. Resolver', country: 'Thailand' },
    }),
  };

  // We could ask for title, year, pages, author { name, country }.
  // Instead we ask only for what this view needs.
  const query = `
    {
      featuredBook {
        title
        author {
          name
        }
      }
    }
  `;

  const result = await graphql({ schema, source: query, rootValue: root });
  console.log(JSON.stringify(result, null, 2));
})();

The resolver returns a rich object with year, pages, and the author’s country, yet none of those appear in the result. The query asked for title and the nested author name, so that — and only that — comes back. Add year to the selection and run again to see the response grow to match.