Facebook recently released their implementation of the GraphQL draft, and I wanted to write to show how to use GraphQL with Flybase.

What is GraphQL?

GraphQL is a query language created by Facebook in 2012 which provides a common interface between the client and the server for data fetching and manipulations.

The client asks for various data from the GraphQL server via queries. The response format is described in the query and defined by the client instead of the server: they are called client‐specified queries.

The structure of the data is not hardcoded as in traditional REST APIs – this makes retrieving data from the server more efficient for the client.

For example, the client can ask for linked resources without defining new API endpoints. With the following GraphQL query, we can ask for the pet specific fields and the linked friends resource as well.

{
	pet(id: 1) {
		name
		type
		friends {
			name
		}
	}
}

In a resource based REST API it would look something like:

GET /pet/1 and GET /pet/1/friends  

or

GET /pet/1?include=friends.name  

GraphQL overview

It’s important to mention that GraphQL is not language specific, it’s just a specification between the client and the server. Any client should be able to communicate with any server if they speak the common language: GraphQL.

Key concepts of the GraphQL query language are:

• Hierarchical
• Product‐centric
• Strong‐typing
• Client‐specified queries
• Introspective

I would like to highlight strong-typing here which means that GraphQL introduces an application level type system. It’s a contract between the client and server which means that your server in the background may use different internal types. The only thing here what matters is that the GraphQL server must be able to receive GraphQL queries, decide if that it is syntactically correct and provide the described data for that.

For more details on the concept of GraphQL check out the GraphQL specification.

Where is it useful?

GraphQL helps where your client needs a flexible response format to avoid extra queries and/or massive data transformation with the overhead of keeping them in sync.

Using a GraphQL server makes it very easy for a client side developer to change the response format without any change on the backend.

With GraphQL, you can describe the required data in a more natural way. It can speed up development, because in application structures like top-down rendering in React, the required data is more similar to your component structure.

Check out our previous query and how similar it is to the following component structure:

	<App>  
		<Pet>
			<Friend/>
			<Friend/>
		</Pet>
	</App>  

Differences with REST

REST APIs are resource based. Basically what you do is that you address your resources like GET /pet/1/friends, which is a unique path for them. It tells you very well that you are looking for the friends of the pet with id=1.

The advantages of REST APIs are that they are cacheable, and their behaviour is obvious.

The disadvantage is that it’s hard to specify and implement advanced requests with includes, excludes and especially with linked resources. I think you have already seen requests like:

GET /pet/1/friends/1/dogs/1?include=pet.name,dog.age

This is exactly the problem what GraphQL wants to solve. If you have types of pet and dog and their relations are defined, you can write any kind of query to get your data.

You will have the following queries out of the box:

• get name of the pet with id=1

  {
  	pet(id: 1) {
  		name
  	}
  }
  

• get names for friends of the pet with id=1

  {
  	pet(id: 1) {
  		friends {
  			name
  		}
  	}
  }
  

• get age and friends of the pet with id=1

  {
  	pet(id: 1) {
  		age
  		friends {
  			name
  		}
  	}
  }
  

• get names of the dogs of the friends of the pet with id=1 🙂

  {
  	pet(id: 1) {
  		friends {
  			dogs {
  				name
  			}
  		}
  	}
  }
  

Simple right? Implement once, re-use it as much as possible.

GraphQL queries#

You can do two type of queries with GraphQL:

• when you fetch (get) data from your server and the
• when you manipulate (create, update, delete) your data

GraphQL queries are like JSON objects without properties:

	// a json object
	{
		"pet": "name"
	}

	// a graphql query
	{
		pet {
			name
		}
	}

I already showed some queries for getting data from the GraphQL server, but what else can we do?

We can write named queries:

	{
		findPet(id: 1)
	}

you can pass parameters to your query:

	query findPet($petId: String!) {  
		findPet(id: $petId) {
			name
		}
	}

GraphQL and Flybase#

Let’s look at how to use Flybase to store data and GraphQL to display it.

The Facebook engineering team open-sourced a GraphQL reference implementation in JavaScript. I recommend checking their implementation to have a better picture about the possibilities of GraphQL.

They started with the JavaScript implementation and also published an npm library to make GraphQL generally available. We can start playing with it and build a simple GraphQL Node.js server with Flybase. Are you in? 😉

The GraphQL JS library provides a resolve function for the schemas:

	pet: {  
		type: petType,
		args: {
			id: {
				name: 'id',
				type: new GraphQLNonNull(GraphQLString)
			}
		},
		resolve: (root, {id}) => {
			flybaseRef.findId(id, function( pet ) {
				return pet.value();
			});
		}
	}

This will return a record with a matching _id as the id we pass to resolve by.

---

We’ve got a repo set up here that you can use to play with the code. It’s still a work in progress since GraphQL is a work in progress itself, but we wanted to share it here early so you can follow along as we dig depper into GraphQL and how it can benefit your apps. So keep an eye on that repo as we build it into something more useful.