Introduction to GraphQL

TL;DR

• 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 "get exactly what you asked for", without any under fetching or over fetching of data.
• GraphQL makes it easier to aggregate data from multiple sources, and uses a type system to describe data rather than multiple endpoints.
• 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 that can be viewed on YouTube.

What is GraphQL?

Quite 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 (realtime updates – most commonly implemented using WebHooks). GraphQL servers are available for multiple languages, including Haskell, JavaScript, Perl, Python, Ruby, Java, C++, C#, Scala, Go, Erlang, PHP, and R.

The attraction for 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 fetching or under fetching, ensuring that apps using GraphQL are fast, stable, and scalable.

To visualise how this would look, let's use the GraphCMS website as an example (disclaimer, I work there) and take a look at the posts on the GraphCMS Academy by running a query asking for just the titles of articles.

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?"
      }
    ]
  }
}

On such a simple request its easy to highlight how the payload would be minimal. However, GraphQL queries access not just the 

fields

To visualise this, let's try a more complex request where we want to see a list of blog posts on GraphCMS, but rather than just the 

postTitle

authors

slugs

categories

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 blog post, because, well, there's a lot) 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"
          }
        ]
      }
}

☝️ that, btw, is a blog post about a great open source reference app on eCommerce - powered by GraphCMS, Gatsbsy, Netlify, Algolia, Stripe, Postmark, and Printful - built by Jamie and Jonathan. Check out the demo deployed on Netlify or fork the repo.

Anyways, back to the topic, 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 of 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.

In summation, the 3 key characteristics of what makes GraphQL a dream syntax are:

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

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 out of Facebook's attempts to scale their mobile app. At the time, their app was an adaptation of their website, when 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 up the iOS from scratch using native technologies.

Brenda Clark put the history of GraphQL quite well on LevelUp's post:

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.

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 into the birth and adoption of GraphQL, with a highly detailed insight into the emergence of the technology.

The documentary can be viewed on YouTube.

Adoption of GraphQL

Understandably, the adoption for GraphQL skyrocketed since the need for such a solution was quite prevalent in the industry. Within half a year there were already implementations of GraphQL in different languages, including PHP, JavaScript, Python, Scala, and Ruby.

Starting off 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 116k stars, a market cap of $4.7 trillion, and a funding of over $9 billion.

Between all the GraphQL servers, clients, gateways, and apps, the GraphQL ecosystem has exploded in terms of 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. In addition, over the last few years, REST has been used to make new APIs, while the focus of GraphQL has been to optimize for performance and flexibility.

When using REST, you’ll always be returned complete "datasets". If you wanted to request information from 

x

x 

• 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 over fetching.

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

productPrice

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

Previously published at https://graphcms.com/academy/what-is-graphql