What is GraphQL?

Key Takeaways

• GraphQL is a modern query language and a runtime for APIs, widely seen as a successor to REST APIs.
• GraphQL is built around the concept of "getting exactly what you asked for"without any data under or overfetching.
• GraphQL makes it easier to aggregate data from multiple sources. It uses a type system rather than multiple endpoints to describe data.
• The GraphQL Landscape shows an aggregated GraphQL adoption table covering over 116k stars, a market cap of $4.7 trillion, and a funding of over $9 billion.
• The team at Honeypot filmed a documentary on the history and emergence of GraphQL.

By now, GraphQL is no longer the “new kid on the block.” You’ve probably heard of it and its comparison with RESTFUL APIs. However, if you are new to using this query language and want to learn how to use it, Hygraph’s GraphQL academy is your place to be.

Being in the GraphQL field for almost as long as it exists, we are profoundly passionate about this topic and want to share our knowledge with you. You'll find everything you need, from the most basic concepts like how GraphQL works to usage topics like GraphQL schema, mutation, subscription, and many more.

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, writing (mutating), and subscribing to changes to data (real-time updates—most commonly implemented using WebhHooks). 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?

The attraction of GraphQL is primarily based on the concept of asking for what you need and receiving just that—nothing more, 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.

Using our website as an example, let's run a query asking for just the titles of articles under the Hygraph Academy to visualize how this would look.

The query would look similar to this:

{
  academyPosts {
    title
  }
}

From here, we can infer that we're just asking for the title of Academy posts and nothing else. Therefore, the results returned would be:

{
  "data": {
    "academyPosts": [
      {
        "title": "Headless Mobile Content Management System (Mobile CMS)"
      },
      {
        "title": "What is Content as a Service (Caas)"
      },
      {
        "title": "Headless CMS and SEO Best Practices"
      },
      {
        "title": "What Is A Headless CMS?"
      },
      {
        "title": "Understanding Digital Experience Platforms (DXP) and Headless CMS"
      },
      {
        "title": "Understanding the Content Mesh and how a Headless CMS fits in."
      },
      {
        "title": "The Era of Application Content"
      },
      {
        "title": "Best Practices for Headless Content Modelling"
      },
      {
        "title": "Choosing the best Headless CMS"
      },
      {
        "title": "What is GraphQL?"
      },
      {
        "title": "Choosing a Headless CMS for Content Creators"
      },
      {
        "title": "Selecting a Headless CMS - a Checklist"
      },
      {
        "title": "What is a DXP (Digital Experience Platform)?"
      },
      {
        "title": "What is the JAMStack?"
      }
    ]
  }
}

It is easy to highlight how the payload would be minimal 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 more complex request: We want to see a list of blog posts on Hygraph, but rather than just the post title, we also want to get the authors these posts are related to, the slugs of the posts, and the categories these blog posts fall under.

The query we'll use for this is:

{
  blogPosts{
    title
    authors {
      name
      twitterHandle
      title
    }
    slug
    categories {
      title
    }
  }
}

The results given back (shortened to just one) look like:

{
  "data": {
    "blogPosts": [
      {
        "title": "Delivering a DIY Store powered by a Headless CMS for ECommerce",
        "authors": [
          {
            "name": "Jamie Barton",
            "twitterHandle": "notrab",
            "title": "Developer Advocate"
          },
          {
            "name": "Jonathan Steele",
            "twitterHandle": "ynnoj",
            "title": "Developer Advocate"
          }
        ],
        "slug": "delivering-a-diy-store-powered-by-a-headless-cms-for-ecommerce",
        "categories": [
          {
            "title": "Content Management"
          },
          {
            "title": "Headless CMS"
          },
          {
            "title": "Projects and Examples"
          }
        ]
      }
}

GraphQL APIs are organized in terms of types and fields, not endpoints, 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.

Why GraphQL?

As you learn how GraphQL works with some examples, it should be apparent that it is fast, stable, and scalable. In summation, 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.

These characteristics make GraphQL data fetching utterly efficient, and offer benefits including easy readability, avoiding under and over-fetching, strong typing, and flexible schema evolution—Discover GraphQL's advantages in more detail here.

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 put the history of GraphQL quite well on LevelUp's post:

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 comprehensible documentary on YouTube about the birth and adoption of GraphQL, providing a highly detailed insight into the technology's emergence.

Adoption of GraphQL

Understandably, GraphQL's adoption skyrocketed since the industry's need for such a solution was quite prevalent. 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.

The GraphQL Landscape shows an aggregated GraphQL adoption table covering over 222k stars, a market cap of $4.7 trillion, and over $9 billion funding.

Between all the GraphQL servers, clients, gateways, and apps, the GraphQL ecosystem has exploded in market adoption, claiming GraphQL's spot as a force to reckon with.

GraphQL vs. REST

A REST API is an "architectural concept" for network-based software. GraphQL, on the other hand, is a query language and a set of tools that operate over a single endpoint. Over the last few years, REST has been used to create new APIs, while GraphQL has been mainly used to optimize performance and flexibility.

When using REST, you’ll always be returned complete "datasets". If you wanted to request information from x objects, you’d need to perform x REST API requests. If you're requesting information on a product for an eCommerce website, your requests may be structured in this way:

• Request productInfo for product names, descriptions, etc. in one request
• Request pricing for prices pertaining to that product in another request
• Request images for product shots from another dataset
• ... and so on

While you'll still get everything you asked for, it would be done in several requests, and each dataset might send you tons of other information you didn't want or need, such as reviews, variations, discounts, etc., depending on how the content/data was structured at each endpoint. On one hand, this is extremely simple - you have one endpoint that does one task, so it’s easy to understand and manipulate. In other words, if you have X endpoint, it provides X data.

Conversely, if you wanted to gather some information from a specific endpoint, you couldn’t limit the fields that the REST API returns; you’ll always get a complete data set - or overfetching.

GraphQL uses its query language to tailor the request to exactly what you need, from multiple objects down to specific fields within each entity. GraphQL would take X endpoint, and it can do a lot with that information, but you have to tell it what you want first.

Using the same example, the request would simply be to get productName, productDescription, productImage, and productPrice from the same endpoint, within one request, and no more. All other content within the database wouldn't be returned, so the issue of over-fetching wouldn't be a concern.

For an amusing ELI5 on the topic, Ben Halpern, the founder of dev.to explains the conceptual differences between GraphQL and REST. Worth a read.

Frequently Asked Questions

What is GraphQL?

GraphQL is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data.

Is GraphQL better than REST?

It depends on the use case. However, the most commonly stated benefit is that GraphQL solves both over-fetching and under-fetching issues by allowing the client to request only the data that is required. Since there is more efficiency associated with working with GraphQL, development is much faster with GraphQL than it would be with REST.

Is GraphQL faster than REST?

GraphQL queries themselves are not faster than REST queries, but since you have full control over what you want to query and what the payload should be, GraphQL requests will always be smaller and more efficient. GraphQL also enables developers to retrieve multiple entities in one request, from one endpoint, further adding to each query's efficiency.

Why is GraphQL so popular?

GraphQL is commonly associated with a better developer experience through team independence and making API versioning redundant. A strongly typed schema, declarative data fetching, and predictable code & payload are other reasons why GraphQL is favored.

How can I learn GraphQL?

If you’re just getting started with GraphQL, Hygraph's GraphQL Academy, How to GraphQL, and FreeCodeCamp are great places to start.

Why use a GraphQL CMS?

Hygraph is a 100% GraphQL Headless CMS. The advantage here is that you can build projects with minimum payload, client-driven data queries, generated documentation, powerful tooling, and extensive filtering for an utterly flexible interaction with your API. The generated GraphQL API works for read and write operations and scales seamlessly.