I was playing with GraphQL (an alternative to REST) recently using a PHP library and was trying to get GraphIQL (note the extra “I”), a web based “IDE” for writing GraphQL queries. This blog post is to save anyone else who stumbles across this post some of the wasted pain I went through. 

TL;DR: Don’t install the software yourself, just install a Chrome extension.

GraphQL 

GraphQL has been open sourced by Facebook (http://graphql.org/). It is not really a “query language for graphs”, but more of a way to do APIs. Facebook being all about social graphs, they use it for APIs to access the Facebook social graph. I think of it more as another way to do a web API (an alternative to REST, JSON RPC, etc). 

There are some great articles on GraphQL, so I am not going to explain it in depth here, but some characteristics that make GraphQL interesting to me include: 

• Schema introspection is built into the spec, making interactive exploration and diagnostic tools possible. 
• Clients are forced to specify the data they want, reducing data volume transfers. It also has nice side effects around upgradability as adding fields on the server never impacts existing clients. 
• There is one URL endpoint. I personally prefer this to REST for writing programs (JSON RPC does this as well). 
• It is gaining some traction (e.g. GitHub have made a GraphQL API available), which means tools are appearing, such as GraphIQL. 

But I don’t think GraphQL is anything magical or revolutionary. It’s another approach with its own pros and cons.

GraphIQL

GraphIQL (https://github.com/graphql/graphiql) is a web based “IDE”, although I think “IDE” is a bit of a stretch. It is more like a web page that allows you to browse around the API with live documentation and autocompletion based on context. The autocompletion is nice, made possible because the server exposes the schema. Again, there are lots of articles out there with screen shots – such as the README file on the GitHub account above.

Installing GraphIQL

And this is where my time wasting started. All the articles I found talked about how to have GraphIQL running in the same NodeJS server as your GraphQL endpoint, to simplify development and debugging of the service. That is all great and well, but I was trying out a PHP version of GraphQL. That is not NodeJS, so I was trying various ways to getting GraphIQL to point to my PHP server instead of the local server.

After several days of frustration, inching my way forwards but hitting all sorts of cross origin access controls (CORS etc), I finally came across several GraphIQL extensions to Chrome. I searched the Chrome App Store for “GraphIQL”, installed one of several options, and life was good. Sigh.

Conclusion

This post was not meant to be a critique of GraphQL (and GraphIQL). But if you are playing around with one of the non-NodeJS GraphQL servers and want to use GraphIQL (and trust me, if you are exploring GraphQL you will want to!) then don’t bother trying to set up the GraphIQL software yourself. Save yourself the pain – just install a browser extension.