Introduction to GraphQL

During the past year or so you might have heard or come across an article about GraphQL, especially if you’re working with React. More recently, GitHub announced GraphQL support to one of their APIs. If you’re wondering what GraphQL is and how it works, below is a quick primer.

In this article, we’ll cover the basics of GraphQL, with some examples of how you can easily test a GraphQL API using Runscope.

What’s GraphQL?

GraphQL is a query language, created by Facebook in 2012. They have been using it internally and in production for a while, and more recently they have published a specification for it, which has received a really positive response from the developer community. Companies like GitHub, Pinterest, and Coursera, have already started adopting it and using externally and internally.

A few advantages of using GraphQL are:

• Hierarchical — query is shaped like the data it returns.
• Client-specified queries — queries are encoded in the client rather than the server. They return exactly what the client asks for, and no unnecessary data.
• Strongly typed — you can validate a query syntactically and within the GraphQL type system before execution. This also helps leverage powerful tools that improve the development experience, such as GraphiQL.
• Introspective — you can query the type system using the GraphQL syntax itself. This is great for parsing incoming data into strongly-typed interfaces, and not having to deal with parsing and manually transforming JSON into objects.

One of the biggest potential advantages when using GraphQL is having an efficient way to get resources from an endpoint by querying for exactly which resources you need. It can also help in retrieving resources that would typically take multiple API calls, by using a single request instead.

Here’s an example GraphQL query to retrieve a specific person from an API:

{
  user(id: 1234) {
    name
    profilePic
  }
}

And here is an example response:

{
  "user" {
    "name": "Luke Skywalker"
    "profilePic": "http://vignette3.wikia.nocookie.net/starwars/images/6/62/LukeGreenSaber-MOROTJ.png/revision/latest?cb=20150426200707"
  }
}

That is a really simple example, but it shows some of the underlying design principles of the language. For example, the user schema could include multiple fields, but our query can define just the necessary information that our application needs.

There’s much more to GraphQL, and I highly recommend heading to GraphQL’s official website and reading through its docs to learn more about it.

How to test a GraphQL API with Runscope?

Testing a GraphQL API with Runscope is pretty similar to testing a REST endpoint. For this example, I’m going to use GitHub’s GraphQL Projects API. It’s still in early access, but it’s easy to sign up for it and start using it.

Let’s start with an introspection query, which will return our API’s GraphQL schema. First, we can set our Authorization header with GitHub’s API key in our Environment settings, which will be shared with all our requests.

GET Introspection query

Next, we can quickly set up our introspection query test by doing a GET to https://api.github.com/graphql:

After that, click “Save & Run” to run the test and get back the full GraphQL schema from the GitHub Projects API.

POST query

We can also test a simple query to get our GitHub username by making a POST query, and adding a JSON body to our request with the query parameter:

The API returns a JSON formatted response to us, and its structure is the same as our request. We can easily add an extra assertion to ensure we’re getting the correct data by accessing the property data.viewer.login:

If you’re still getting familiar with writing queries, it can easier to first build your queries using GitHub’s GraphQL Explorer, and then paste them in your tests.

POST query with arguments

Here are a couple more example queries that we can make. First, we can make a query to get an issue ID from a repository, and save that as a variable for use in later tests:

POST mutation

Next, we can use a mutation query to add a reaction to the issue we grabbed in our last test:

What's next

GraphQL is still in its early stages, but it already has an active and lively community, and it’s being adopted by some big companies. There are a lot of challenges ahead of it becoming more widely used, but just like any other API, testing and monitoring to make sure that everything is 200 OK is crucial.

Update: Check out Phil Sturgeon's guest blog post on "You Might Not Need GraphQL".

Everything is going to be 200 OK®

Originally published at blog.runscope.com.