Introduction to GraphQL & BigCommerce

GraphQL 101

Companies like Airbnb, The New York Times, and Yelp all use the GraphQL query language to get server-side data they need to power their front ends. GraphQL has grown steadily in popularity since its creation at Facebook in 2012 , but adoption really took off when it went open source in 2015.

At BigCommerce, we saw huge potential with GraphQL for making it easier to build custom storefronts. We developed a GraphQL Storefront API that does just that! This API is in Open Beta today and available for all stores.
Sounds exciting, right? But… what is GraphQL? How does it work under the hood and how can it fit into an ecommerce tech stack? Let’s dive in and learn more about the web’s buzziest query language.

What is GraphQL?

GraphQL is an open-source syntax and query processor for APIs.
In short, it is a very concise way to ask for data via HTTP protocol. Although the “QL” in GraphQL stands for query language, it is not technically a query language. GraphQL is actually several things!

GraphQL is defined by sets of types and fields and has its own syntax. In that sense, it is very much like a language. But it is also an execution engine with defined schema and resolvers that processes a request and returns relevant JSON. The schema defines which queries your GraphQL server accepts, and the resolver functions serve up your data. Another facet of GraphQL is it’s actually a set of specifications and conventions maintained by the Open Web Foundation. These rules are high level and allow developers plenty of flexibility to adapt their GraphQL implementation to fit their needs.
Let’s take a look at an example GraphQL query. Here, we’re getting a list of heroes:

From GraphQL.org

{
 hero {
 name
 }
}

This query returns:

{
 “data”: {
   “hero”: {
     “name”: “R2-D2”
    }
  }
}

A feature that makes GraphQL so attractive is the request model matches the response. You can expect how the data that you get back in your response will look, which makes processing it easy. And because you’re hitting a single endpoint, you can structure your queries to minimize the number of HTTP requests needed to get the data you care about — which is of critical importance in environments where the overhead of requests and the consequences of over-fetching actually affect business outcomes, such as when serving up a shopping experience to a browser!

Brief History of GraphQL

Facebook architected GraphQL as they were rehauling their mobile apps in 2012. This proved difficult to do because of the complexity of all the data served up in a typical Facebook view. They needed a data model that was more representative of connections (a graph with lines) versus join tables of data. This is because that is a closer representation of what Facebook data actually is. To match this, they began development on what we know as GraphQL. Facebook’s team also considered the needs of designers and front-end developers when creating a solution for storing and retrieving data more intuitively. With GraphQL, there’s no need for multiple API calls or parsing through large return request bodies to get the information that matters to users.

What Problems Does GraphQL Solve?

GraphQL is advantageous over traditional RESTful APIs in several ways. As websites begin to behave more like full applications, GraphQL helps solve many data architecture issues that can arise when client-side views must change often to reflect user preferences. As a mobile-first paradigm becomes the standard for sites across the web, it’s also important for developers to adapt to faster, leaner ways of retrieving only the data that the user needs, and nothing more.

Over and Under-fetching

Earlier, we saw an example of a request using GraphQL where we retrieved a hero. That’s great, but what if we needed a list of the hero’s friends too? With a traditional RESTful API, we might need an additional call to another endpoint heroes/friends, or heroes/friend/{friend-id}to get that data. With GraphQL, you can expand your query with little worry about getting back too much data when all you needed was something simple.

From GraphQL.org

{
 hero {
  name
  friends {
  name
  }
 }
}

Strong Type System

GraphQL is a strongly-typed language, which means the technology’s compiler is strict in the values that it will accept. This lets GraphQL return error messages that are more meaningful.

Single Endpoint

An important feature of GraphQL to call out is that all requests go to a single endpoint. What this means is a change to your front end (view) doesn’t have to result in back end re-architecture each time. You can accommodate market trends and incorporate user feedback quickly without wrangling and tweaking your models and controllers, just to show users a new piece of information.

GraphQL at BigCommerce

The BigCommerce Storefront GraphQL API allows you to programmatically retrieve all of the data that you can interact with via our built-in front end framework, Stencil. In my totally unbiased opinion, this is a huge deal. Why? Let’s look at an example. Before the GraphQL API, if you wanted to access some information about a product that was not available via Stencil Objects, you needed to make an authenticated API call via your server-side code to retrieve what you needed. And even then, you had to parse through the request response body to find the nugget of data you were looking for. Also consider: what if you needed to make another call for additional information based on the first’s response? This workflow wasn’t ideal and could lead you down a rabbit hole of hacky workarounds. This is what getting a single product’s price looks like using the BigCommerce GraphQL API:

query SingleProduct {
  site {
    products (entityIds: [4917]) {
      edges {
        node {
          id 
          entityId
          name
          prices {
            price {
              value
              currencyCode
            }
          }
        }
      }
    }
  }
}

And the response:

{
  "data": {
    "site": {
      "products": {
        "edges": [
          {
            "node": {
              "id": "UHJvZHVjdDo0OTE3",
              "entityId": 4917,
              "name": "Longsleeve Denim Shirt",
              "prices": {
                "price": {
                  "value": 129,
                  "currencyCode": "USD"
                }
              }
            }
          }
        ]
      }
    }
  }
}

Dead 💀. Simple. With the GraphQL API, we want to simplify developer workflows to make building a shopper’s experience the priority. That way, developers can spend less time finding loopholes around limitations and more time designing a bespoke experience for shoppers. We also received feedback from devs who felt constrained to work within Stencil. The GraphQL API fully frees you from sticking with our built-in view and opens the door to all kinds of solutions surrounding headless commerce. You no longer have to compromise on the technology you can use on the front end, but still get all the benefits of the BigCommerce back end. ✨

With regard to headless, all kinds of useful things are built into this API. The Storefront API already takes into account the logged-in shopper, so that’s not something you need to worry about in your code. If you make a call to grab pricing for a product, you’ll receive that user’s pricing without needing to go through any additional steps.

The BigCommerce Storefront API opens up a lot of possibilities for customizing shopping experiences within our built-in theme engine, Stencil. A common piece of feedback we’ve heard has to do with being able to surface catalog data in custom sections of the theme, wherever shoppers tend to look. There are no more constraints around this. Show shoppers t-shirt colors and variant pricing anywhere! On the home page? Yes. The category page? Also yes. 👕

Looking further ahead, we can envision all kinds of interesting builds, like checkout kiosks and custom mobile apps. The possibilities are very open. 🙌🏼

Tools and Resources

Apollo

In a nutshell, Apollo is a service that acts as a connection layer between a GraphQL back end and most front ends. React, Vue & Angular are the most popular frameworks to pair with Apollo. It abstracts away the difficulty of creating your own queries and object types!

GraphQL Playground

BigCommerce’s GraphQL API uses GraphQL Playground to let you run requests in the browser. Try it!

Syntax Cheat Sheet

Fast track your understanding with this handy GraphQL cheat sheet and quickly get up to speed.

Conclusion

If this post has you excited about the possibilities of GraphQL, that makes two of us! Why don’t you check out our Developer Documentation to get started on a new GraphQL + BigCommerce project, or have a look at a BigCommerce example app built with Bootstrap/VanillaJS/GraphQL Storefront API? 💗