GraphQL in iOS — Part 1: What is GraphQL?
A conversation at 5h pm.
Front-end guy: Hello, can you add job and marital status to object Person in your JSON response? Boss asked me to display these information in the UI.
Back-end dude: Ok lah. It’s very easy. Give me 5 mins max.
1 hour after
Front-end guy: Have you finish it yet?
Back-end dude: Oh I’m sorry, I have an urgent task. I will do it for you tomorrow. Now I’m coming home.
Front-end guy: Well… OK. Let’s get it done tomorrow. It’s not quite urgent.
A day after:
Front-end guy: Hey, the API still not return what I want. Why taking it so long man?
Back-end dude: OMG. I forgot to tell you I’m taking vacation for 1 week from today. I will do it for you next week when I get back.
Front-end guy: F*ck youuuu!
1 min later:
Front-end guy: Hey boss, I quit!
Boss: ???
Have you ever jump to that situation?I guess many times. Sometimes you just want to have a little modification in the response but still need to contact to back-end team to adjust the whole flow. Or maybe you can handle yourself but need to call multiple API to get what you want. So annoying, so time consuming. Your task is pending, the deadline is close but you have to wait for other people. Don’t worry, here comes GraphQL.
GraphQL is a query language, created by Facebook in 2012, open-sourced in 2015 and still in its evolution. It removes many of the inefficients with REST API. Instead of dealing with multiple endpoints in REST, now we have only 1 exposed endpoint and the client can define precisely what data they want.
In this topic, I will not go into details of how GraphQL works, but I will introduce what is GraphQL and the basic of it, then make a small demo using Graphcool to create a GraphQL back-end.
In the situation on the top, here’s the details of the JSON response
{
person {
id
name
age
}
}The object Person returned by the server has 3 fields: id, name and age. Now you want to know more properties of Person. Instead of asking the server to modify the API, in GraphQL, you only need to declare more fields in your query.
{
person {
id
name
age
job
maritalStatus
}
}Instead of jump straight into the syntax of GraphQL, let’s build a small GraphQL server first. Graphcool is one of the best choice for you to try GraphQL. It’s free for developer purpose and very easy to use.
Build GraphQL server:
First, go to https://www.graph.cool/ and start for free. You can create a new account or use your existing Github/Gmail account.
After logging in, you can create your project. There’s a way to create and manage project by using command line using Graphcool CLI, but I don’t use it here because Graph.cool already provides enough capabilities for demo purpose.

As you can see, it looks like other DB. On the right of the screen, you can see some tables call File and User. This is pre-defined table and you can’t delete them. Here, a table is call a type and all implements Node type. Try remove the code blocks of type File and click Preview Changes, you will get this error:

Now click add type and add your new type. I will add a type called Girl.

You can see there are 3 fields with the lock icon: id, createdAt and updatedAt. These 3 fields are system fields and auto filled, so you can’t modify them.
Now, we will open playground to do some simple examples with GraphQL. I’ve already input some data.

To open playground, you can press PLAYGROUND button. If you want to open Playground in full screen, click Endpoint, you will find a link which has format: https://api.graph.cool/simple/v1/xxx. xxx is your API key.
Now you opened Playground, let’s talk about GraphQL syntax. GraphQL syntax is called GraphQL Interface Definition Language (IDL). It has some basic components:
- Field: simply a property of your object
- Argument: when making a query, you can pass argument to field to retrieve exactly what you want
- Alias: let you rename the result of a field to anything you want
- Fragment: a set of fields, which you can reuse and include in query wherever you need to
- Variable: it seems confuse between argument and variable. But they still have differences. In your application, your argument will be dynamic. We can’t pass these arguments directly to the query string, because it will cause many troubles to re-structure the query string whenever the argument change. So we need to use variable. Variable starts with $, follow by its name.
- Query: to retrieve the data
- Mutation: to alter (create, update, delete) data
You can read more about those things in this link: http://graphql.org/learn/
Now let’s get to some simple example:
First, we will create a new girl info.

This mutation will create girl with name, age and height. Note here that you don’t need to provide id, createdDate and updatedDate because those are auto fields. Inside the bracket is the field you want to get back after the mutation succeed.
Now, query information

This query will return all girls, which id and name of each girl. When you are typing, the console will auto suggest the syntax of GraphQL for you.
So, what if I need to choose a girl with specified id? Let’s try:

Suppose you know the id of that girl, you can pass the id as the argument of the field. Instead of id, what if I want to pass name of that girl?

WTH? I’m sure 1000% that Girl has a field called name. The problem here is that name is not unique, and name is not the valid argument on this field. The response may return more than 1 girl, so we need to use filter instead.

We will filter the girl whose younger than 25 by using filter. In the bracket after filter: , you can add more condition. When you type filter, the playground will open a suggest box. Click on GirlFilter to see more filter operators that can apply for this field.

Now come to update

I have updated age of Emiri Suzuhara from 23 to 20. Finally, we will try to delete

If you continue to delete the same id, error will happen:

Ok. It’s the end of this part. This is some basic to help you understand what GraphQL is and some simple examples about how to use it. Next part is about how to use GraphQL in your iOS app.
Stay tuned!
