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.
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.
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.
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.