What is GraphQL?

GraphQL is a query language for APIs and a runtime for executing those queries against your data. Developed by Facebook (now Meta) and open-sourced in 2015, GraphQL allows clients to request exactly the data they need — no more, no less — in a single request.

Unlike traditional API approaches where the server determines the shape of the response, GraphQL puts the client in control. The client writes a query describing the fields it wants, and the server returns a JSON response matching that exact structure.

GraphQL vs. REST

REST APIs expose data through multiple endpoints (e.g., /api/articles, /api/articles/123, /api/authors/456). Each endpoint returns a fixed data structure defined by the server. To assemble a page that shows an article with its author and related articles, a REST client might need to make several separate requests.

GraphQL uses a single endpoint. The client sends a query specifying all the data it needs, and the server resolves it in one round trip. This addresses two common issues with REST:

• Over-fetching: REST endpoints often return more data than the client needs. A /api/articles/123 response might include dozens of fields when the client only needs the title and summary.
• Under-fetching: Getting related data (like the author of an article) often requires additional requests. GraphQL lets you traverse relationships in a single query.

Here is a simple example of a GraphQL query:

query {
  article(id: "123") {
    title
    summary
    author {
      name
    }
    relatedArticles {
      title
      url
    }
  }
}

This returns only the requested fields, nested exactly as specified.

Trade-offs

GraphQL is not universally better than REST. REST APIs are simpler to cache (HTTP caching works naturally with distinct URLs), easier to learn, and sufficient for many use cases. GraphQL adds complexity on the server side — resolvers, schema management, and query performance considerations — that may not be justified for simple APIs.

GraphQL is most valuable when clients have varied data needs, when reducing network requests matters (mobile apps, for example), or when the data model involves complex relationships.

How Decoupled.io Uses GraphQL

Decoupled.io leverages GraphQL as one of its core API layers. Drupal's content model — content types, fields, taxonomies, and relationships — is exposed through a GraphQL schema that clients can query.

For most use cases, the recommended approach is the Typed Client, which provides a higher-level, type-safe interface built on top of GraphQL. The typed client handles query construction, type generation, and response parsing automatically, so developers get the benefits of GraphQL without writing raw queries.

For advanced use cases or custom integrations, the GraphQL API is also available directly, giving full control over query structure and data retrieval.