Every language needs a grammar. If GraphQL is the language you can use to talk to an API, the GraphQL type system gives you the grammar that will make sure your queries are properly formatted and understood.
Just like a programming language, GraphQL relies on types to define and describe every element you will find in an app. In other words, types are the building blocks of a GraphQL API.
There are several main categories of types in GraphQL, namely: data types, object types and operation types.
Data types: what the data looks like
OK, let’s start with the basics. Data types offer a description of every form a piece of data can have. This is not unlike the data types you will find in a programming language.
There are six data types in GraphQL and every piece of data accessible through an API must be of one of these types:
Scalars: these are basic value types such as String (a UTF-8 text input), Int (an integer), Float (a floating point number), Boolean (True or False) or ID (a unique identifier given by the app to an object in its database).
Enums: these are used to define a list of possible values to choose from. Think of this as the equivalent of a drop-down list on an online form.
Objects: these are used to define data structures that have a series of attributes. As an example, an object can be a registered user (with a username, e-mail, phone number, etc), an article on a news web site (with a title, a subtitle, a body, etc), a product on an online store (with a name, a SKU, a price, etc) and so on. We’ll delve deeper into object types in a minute.
Inputs: these can be used as arguments for mutation operations, to pass data when creating new objects (relax, I’ll clarify arguments and mutations in a later post as we go along).
Unions and Interfaces: these data types are used to allow access to different object types with some common features (sorry for the oversimplification). We’ll worry about them later.
Bottom line: Scalars, Enums, Objects and maybe Inputs are the data types you first need to get your head around at this stage.
Object types: the actual content you can access
Let’s take a closer look at the Object data type. An object describes an element that has a number of attributes that may be of interest to a user querying the GraphQL server. These attributes are listed as fields.
Here’s an example:
In GraphQL, items can be either types or fields. In the example above, types are in white and fields are in red.
Here we are displaying an object type called User. This object type is used to describe the users in the GraphQL server’s database. In our example, users have three attributes: an identification (id), a name (name) and an e-mail (email). These are the fields containing the data we will be able to access for a given user by querying the GraphQL server.
You can see the id field uses the ID data type. The name and email fields both use the String data type. With the information above, we know exactly what a User object looks like.
Note the exclamation mark at the end of the data type mentioned for each of the three fields. This indicates these fields must have a value. When creating or modifying a user, we cannot leave these fields empty.
Let’s look at another example:
Objects can have nested objects. This means an object can be an attribute of another object.
Here, we have two object types called Author and Book. You can see that the Book object has an author field whose data type is Author. When querying a Book object, we can therefore obtain details of both the book itself and its author.
Note that if the id, name, title and author fields must have a value (data type ends with an exclamation mark), the birthYear and publicationYear fields can be left empty.
You may also have noticed something else in the examples above: fields are lowercase, whereas types are capitalized. This is a convention in GraphQL.
Still with me? Good. Here is something else you need to know. In the example below, you will see that the type of the books field in the Author object type is within brackets. This means this field will return an array of objects. In the present case, querying the Author object and including the books field in the query will return information on a given author, including a list of all the books they published.
Operation types: how you talk to an API
So now we know everything in GraphQL is either a field or a type. This is also the case for the operations we can use to access of modify data through an API. These operations car be either queries, mutations or subscriptions (more on these in this post).
These operations types are also defined using the type system. Here is an example:
In the example above, we have an operation type called Query. This type lists all the query operations we can use to access data through the API. In the above example, there is only one query we can use and that the API will understand: getUser. In a real life scenario, though, a GraphQL API will typically offer a longer list of queries.
By using getUser, we can query the API for the details of a given user. We do this by specifying this user’s identification in the id field (which as we can see uses the ID data type and is a required attribute).
The operation will return data from this user’s User object.
Don’t worry if this all seems a bit abstract. What you need to take away is that the operations you may use to access a GraphQL server are also defined using the type system, just like everything else in GraphQL.
This means even though the GraphQL language allows for a lot of flexibility in writing queries, you will only be able to use operations that have been defined for this given API.
Closing note
Listing all the different types that exist for a given GraphQL API (and therefore all the types you can use in your queries) is the job of the GraphQL schema. The schema is the foundation of a GraphQL API. Think of it as a dictionary that lists everything you need to know to understand (and hack) a given API.
The schema is an essential concept to understand in GraphQL. Here I have a full blog post to walk you through.
Also, if you’re hungry for more and want the full story on GraphQL data types (and on everything else related to hacking GraphQL), I strongly suggest reading Black Hat GraphQL, by Dolev Farhi and Nick Aleks. It’s the best reference I’ve seen so far and a good share of what I know about GraphQL comes from this book.
Finally, you can check out Introduction to GraphQL which is also a good entry point, although not specifically hacker oriented.
