Key Takeaways

• GraphQL is a query language for APIs and a runtime that answers those queries against a typed schema.
• Clients ask for exactly the fields they need and get them back in one request, without over- or under-fetching.
• One schema can describe data from many sources, so apps query a single endpoint instead of stitching together several.
• That same typed schema gives AI agents a machine-readable map of your data, which is why GraphQL is back in the conversation in 2026.

GraphQL is a query language for APIs and a server-side runtime that answers those queries with your existing data. Instead of calling several fixed endpoints, a client sends one query to one endpoint, names the exact fields it wants, and gets back JSON in that same shape, checked against a typed schema.

We've worked with GraphQL for almost as long as it has existed, so this academy is where we share what we've learned. This page covers what GraphQL is, how it works, how it compares to REST, and where it fits now that AI agents read APIs too. When you're ready to go deeper, follow the learning path at the end, from schemas and queries to caching and federation.

What is GraphQL?

Simply put, GraphQL is a query language for APIs and a runtime for fulfilling those queries with existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

GraphQL supports reading (querying), writing (mutating), and subscribing to changes in data. Subscriptions deliver real-time updates and usually run over WebSockets. GraphQL servers are available for multiple languages, including Haskell, JavaScript, Perl, Python, Ruby, Java, C++, C#, Scala, Go, Erlang, PHP, and R.

How does GraphQL work?

GraphQL works in three steps:

1. Define a schema: the server describes its data as types and fields, and how those types relate. Read more in GraphQL schemas and types.
2. Resolve fields: each field has a resolver, a function that fetches its value from a database, a service or another API.
3. Ask for exactly what you need: the client sends a query naming the fields it wants. The server validates it against the schema, runs the resolvers and returns JSON in the same shape as the query.

The attraction of GraphQL is primarily based on the concept of asking for what you need and receiving just that, nothing more and nothing less. When sending queries to your API, GraphQL returns a very predictable result without any over- or under-fetching, ensuring that apps using GraphQL are fast, stable, and scalable.

Our own website runs on Hygraph, so let's use it as the example. Here's a query asking for just the titles of the articles in this GraphQL academy:

query AcademyTitles {
  learnTopic(where: { slug: "graphql" }) {
    name
    articles {
      title
    }
  }
}

We're asking for the topic's name and the title of each article in it, and nothing else. Therefore, the results returned are:

{
  "data": {
    "learnTopic": {
      "name": "GraphQL",
      "articles": [
        { "title": "What is GraphQL?" },
        { "title": "Schemas and Types" },
        { "title": "Queries" },
        { "title": "Mutations" },
        { "title": "Subscriptions" },
        { "title": "Variables" },
        { "title": "Fragments" },
        { "title": "Introspection" },
        { "title": "Pagination" },
        { "title": "Errors" },
        { "title": "Authentication & Authorization" },
        { "title": "Federation" },
        { "title": "Caching" }
      ]
    }
  }
}

It is easy to see how small the payload stays on such a simple request. However, GraphQL queries access not just the fields of a single resource but also follow references between them. While typical REST APIs require loading from multiple URLs, GraphQL APIs get all the data in a single request, making apps quick even on slow mobile network connections.

To visualize this, let's try a richer request. We want a blog post on Hygraph, but rather than just the title, we also want its slug, the authors it's related to, and the category it falls under.

The query we'll use for this is:

query BlogPostWithAuthors {
  blogPosts(first: 1, where: { slug: "graphql-vs-rest-apis" }) {
    title
    slug
    authors {
      fullName
    }
    blogPostCategory {
      name
    }
  }
}

The result looks like this:

{
  "data": {
    "blogPosts": [
      {
        "title": "GraphQL Vs. REST APIs: A comprehensive comparison for developers",
        "slug": "graphql-vs-rest-apis",
        "authors": [
          { "fullName": "Ronak Ganatra" }
        ],
        "blogPostCategory": {
          "name": "Developer tutorials"
        }
      }
    ]
  }
}

GraphQL APIs are organized in terms of types and fields, making them extremely easy to get up and running since you can access all your data from a single endpoint. GraphQL uses types to ensure apps only ask for what's possible and provide clear and helpful errors. Apps can use types to avoid writing manual parsing code.

Core building blocks of GraphQL

Every GraphQL API uses the same handful of pieces, and each has its own article here.

Schema and types

The schema is the contract between server and client. It lists every type, field and relationship, written in the Schema Definition Language. Start with schemas and types.

Queries

Queries read data. The client picks the fields, and the response mirrors that selection. See GraphQL queries.

Mutations

Mutations create, update and delete data, then return whatever changed. See GraphQL mutations.

Subscriptions

Subscriptions keep a connection open so the server can push updates when data changes. See GraphQL subscriptions.

Variables

Variables pass dynamic values into an operation, so you write a query once and reuse it. See GraphQL variables.

Fragments

Fragments bundle a set of fields you can reuse across queries and components. See GraphQL fragments.

Introspection

Introspection lets a client ask the API to describe its own schema. Tools, IDEs and AI agents use it to discover what they can query. See GraphQL introspection.

Why GraphQL?

The examples above show why teams pick GraphQL for speed, stability and scale. These are the 3 key characteristics that make GraphQL a dream syntax to use:

1. Clients can specify exactly what data they need
2. Aggregating data from multiple sources is easy with GraphQL, and
3. GraphQL uses a type system to describe data rather than endpoints.

Together they bring readable queries, strong typing and flexible schema evolution. Discover GraphQL's advantages and disadvantages in more detail.

GraphQL vs. REST

REST is an architectural style for network-based software, where each resource lives at its own URL. GraphQL, on the other hand, is a query language and a set of tools that operate over a single endpoint.

With REST, each endpoint returns a fixed dataset. Product details for an eCommerce website might take one request for productInfo, another for pricing and a third for images, and each response can carry data you never asked for, such as reviews, variations or discounts. On the plus side, REST is simple: one endpoint does one task, so it's easy to understand and to cache.

GraphQL tailors the request to exactly what you need. The same product page asks for productName, productDescription, productImage and productPrice from one endpoint, in one request, and gets nothing more.

For a full breakdown, read our GraphQL vs. REST comparison.

Is GraphQL still relevant in 2026?

Yes. GraphQL is still a strong choice for apps that pull related data from several sources into several front ends, and for APIs that AI agents need to understand.

It doesn't fit every project. REST is simpler for small, resource-shaped APIs and gets HTTP caching for free, while GraphQL asks for resolvers, query cost limits and a caching strategy on the server.

Where GraphQL earns its place is content that's relational and reused: products, articles, authors, locales and campaigns that show up on a website, an app and a kiosk at once. One query per screen beats a chain of REST calls there.

The newest reason is AI. Agents work best with APIs that describe themselves, and most APIs aren't built that way yet. Only 24% of developers design APIs with AI agents in mind today. A typed, introspectable GraphQL schema already does that work. Still deciding? Read whether GraphQL is right for your project.

GraphQL and AI agents

An AI agent can only work with your content when it understands it: which types exist, how they connect, and which fields matter. Most organizations aren't there yet. 63% of organizations either don't have, or aren't sure they have, the right data management practices for AI. GraphQL covers a big part of that gap by design.

The schema is a contract agents can read

A GraphQL schema spells out every type, field and relationship, with names and types an agent can trust. There's no undocumented endpoint to guess at.

Introspection is discovery

Through introspection, an agent can ask the API what it offers and plan its query from the answer, the same way your IDE autocompletes fields.

Field selection keeps context small

Agents pay for every token they read. Because a query returns only the fields it names, the agent pulls a title and a summary instead of a full record with everything attached.

MCP connects the agent, GraphQL describes the data

The Model Context Protocol (MCP) is the open standard that connects an AI assistant to tools and data. MCP handles the connection; the GraphQL schema tells the agent what's on the other side.

Here's how that looks with Hygraph, the agentic content platform and headless CMS. Connect Claude Code to your project through the Hygraph MCP server and ask it to list every article in your GraphQL course. The agent reads your schema, sees that a learn topic has articles, and writes a query like the AcademyTitles example above. The same setup works in Cursor, VS Code and Windsurf. The MCP server uses the permissions of the access token you give it and can't delete or unpublish content, so your team stays in control. For agents that work inside your editorial workflow, see Hygraph AI Agents.

The history of GraphQL

Similar to React, GraphQL was developed internally by Facebook in 2012 before being publicly released in 2015. Following GraphQL's transition to being made open source, the GraphQL project was moved from Facebook to the newly established GraphQL Foundation, hosted by the Linux Foundation, in 2018.

The origin of GraphQL comes from Facebook's attempts to scale its mobile app. At the time, their app was an adaptation of their website, and their mobile strategy was to simply "adopt" HTML5 to mobile. Due to issues related to high network usage and a less-than-ideal UX, the team decided to build iOS from scratch using native technologies.

Brenda Clark summed up the problem the Facebook team faced:

"The main problem with Facebook's News Feed implementation on mobile. It wasn't as simple as retrieving a story, who wrote it, what it says, the list of comments, and who's liked the post. Each story was interconnected, nested, and recursive. The existing APIs weren't designed to allow developers to expose a rich, news feed-like experience on mobile. They didn't have a hierarchical nature, let developers select what they needed, or the capability to display a list of heterogeneous feed stories."

Brenda Clark, on the Level Up Coding blog

Long story short, the core team at Facebook decided they needed to build a new News Feed API, which is when GraphQL began to take shape. Over the next several months, the surface area of the GraphQL API expanded to cover most of the Facebook iOS app, and in 2015, the GraphQL spec was first published along with the reference implementation in JavaScript.

The team at Honeypot made a documentary on YouTube about the birth and adoption of GraphQL, with a detailed look at how the technology emerged.

Adoption of GraphQL

GraphQL's adoption took off quickly because the industry needed it. Within half a year, there were already implementations of GraphQL in different languages, including PHP, JavaScript, Python, Scala, and Ruby.

Starting as a "hobbyist" spec, GraphQL rapidly gained enterprise validation and was adopted by companies like GitHub, Yelp, Airbnb, and many more. Between all the GraphQL servers, clients, gateways, and apps, the ecosystem is now a standard part of how teams build APIs.

How to learn GraphQL with the Hygraph academy

Work through the academy in this order: the first seven articles teach the language, the last five cover production.

1. Schemas and types: model your data in SDL, from scalars to unions.
2. Queries: nested queries, filters, named queries and aliases.
3. Mutations: create, update, delete, plus bulk and nested writes.
4. Variables: stop hardcoding arguments.
5. Fragments: share field sets between components.
6. Subscriptions: real-time updates from the server.
7. Introspection: let tools and agents explore your API.
8. Pagination: offset and cursor patterns for long lists.
9. Errors: read and handle partial responses.
10. Authentication and authorization: control who sees what.
11. Caching: speed up repeat requests on client and server.
12. Federation: combine several services into one graph.

Want to try queries as you go? Open the GraphQL playground and run them against a sample API.