GraphQL is something you may have heard in passing, usually from the web team. It's a Facebook API technology, that describes itself as a A Data Query Language and Runtime. GraphQL is a spec, and there are multiple implementations of it. As mobile engineers, we can consider it an API, where the front-end team have as much control as the backend.

This blog post covers our usage of GraphQL, and what I've learned in the last 3 months of using it in Eigen.

So what is GraphQL

You can get the full explanation on the GraphQL website. Though, I found running through Learn GraphQL site to really hammer down how it works. Reading the introduction blog post can be useful too.

We use GraphQL as an API middle-layer. It acts as an intermediate layer between multiple front-end clients and multiple back-end APIs. This means it can easily coalesce many API calls into a single request, this can be a massive user experience improvement when you have a screen that requires information from varied sources before you can present anything to a user.

As a client, you send a "JSON-shaped query" structure, which is hierarchical and easy to read:

1 2 3 4 5 6 7 8 9 { artwork(id: "kimber-berry-as-close-to-magic-as-you-can-get" ) { id additional_information is_price_hidden is_inquireable } }

This will search for a specific artwork, sending back the Artwork's id , additional_information , is_price_hidden and is_inquireable .

It's important to note here, the data being sent back is only what you ask for. This is not defined on the server as a short or embedded version of a model, but the specific data the client requested. When bandwidth and speed is crucial, this is the other way in which GraphQL improves the app-user experience.

That's the two killer features:

Coalesce Multiple Network Requests. Reducing the amount of network requests that need to be made. Only Send The Data You Want. Only sending the data you are interested in.

With mobile apps you're working with unreliable, slow networks with high bandwidth costs. Optimising towards less networking with richer data means your app is more resiliant to things outside of your control.

This is in stark contrast to existing API concepts, like HAL and JSON-API - both of which are optimised for caching, and rely on "one model, one request" types of API access. E.g. a list of Artworks would actually contain a list of hrefs instead of the model data, and you have to fetch each model as a separate request.

Using GraphQL

Artsy's GraphQL server is (unsurprisingly) open-source, it's at artsy/metaphysics. However, it's not publicly accessible, (yet?). One of the coolest things about developing against a GraphQL server is GraphiQL - an IDE for exploring your API. I can't show you ours, but I can send you to Clay Allsop's GraphQLHub:

Here ( I strongly recommend pausing to open that link in a new window. Press cmd + enter to see the results. We also have an example of refactoring that request here. )

GraphQL comes with a playground for the API! It's amazing! Clay called it the "Killer App" of GraphQL - I'm inclined to concur. I've never had API docs this useful. This is built on top of the schema/docs/type reflection APIs inside the GraphQL spec.