GraphQL and The Open Movie Database. From introspection to Inception.

I recently returned from React Europe 2015 where Facebook released GraphQL, it's been in production use at Facebook for several years. In a nutshell a GraphQL API opposes REST and add-hoc endpoints, it allows a client to efficiently get all the data it needs in one network request, and it allows a developer to concisely and declaratively express their apps data requirements. 

They released two things: the GraphQL spec and GraphQL.js which is a JavaScript reference of the spec. To learn GraphQL I suggest reading the GraphQL Introduction blog, the spec and the Star Wars specs inside the GraphQL.js repo. 

Using node with restify and GraphQL.js I have created a small app that lets us query The Open Movie Database with GraphQL. My apps github repo is here and it's hosted at https://omdb-graphql.herokuapp.com. This endpoint accepts POST requests with a GraphQL query in the body and it will return a JSON result. There isn't much to my app, the meaty GraphQL file is here and the rest is a vanilla restify app.

A cool feature of GraphQL is introspection. By definition this means "the examination or observation of one's own mental and emotional processes". And in this context it means we can inspect the GraphQL schema with GraphQL queries! So lets pretend your busy project manager pinged you my GraphQL endpoint https://omdb-graphql.herokuapp.com and asked you to make a feature for looking up film details. But as you go to ask for the API documentation link you remember introspection! Lets query my endpoint and learn what it can do, then make a query to fetch a movies data.

First of all lets look at the query type in it's schema. This is the top level entry point into the system and it's compulsory every GraphQL schema has one.

Here we can see the query object has a field on it called movie that takes a compulsory argument called title in the form of a string. The field returns the Movie type which is of the kind OBJECT, lets take a look at it.

Now we can see all the fields the Movie type has. They mostly all return strings or lists of strings, but the imdb field returns an Imdb type. Let's take a look at that.

The Imdb type has three fields on it. But they have scalar kinds not seen before. The IMDb id of the film is an ID, the rating is a Float and the votes count is a Int.

Great so know we understand the Movie object and it's nested Imdb object. Let's query for the film Inception!

Notice how with GraphQL queries the data we get back matches identically the shape of the query. This is awesome for client developers because they know exactly what they will get back. No custom parsing logic etc. Also, it's important to note no excess data is returned in the response. This is usually known as over fetching. For example imagine I just needed the movies director. In a REST api I would wastefully have to get the whole movie object sent down the wire even though I only want one attribute! 

If you want to play with this GraphQL endpoint I suggest using Postman. Simply send POST  requests to https://omdb-graphql.herokuapp.com with a raw GraphQL query in the body and you will get the JSON result. I lied above, the query type has an extra field on it, see if you can find it...

A few of us are super keen to use GraphQL in production here at Red Badger. Be interesting to see how it unfolds. Follow us if you're interested.