Mar 5 2019

GraphQL 101 Quick Start

GraphQL is the new database management from the Facebook team, which now outsourced. This article is a quick reference from what I’ve learned about it with autodidact. My article may miss some of the concepts as I can’t find a proper “for dummies” tutorial about GraphQL out there but should be sufficient for beginners as a stepping stone for more advanced concepts.

This GraphQL article is made using Graphcool as Server As A Service, and Apollo for the plugins. I’ll try to steer clear from a specific platform implementation, and just focused on GraphQL queries and mutations, as well as how to implement it in Apollo client. Feel free to skip over some steps if you’ve already done it.

Preparation

  1. Install Homebrew cmd.
  2. Using Homebrew, install npm cmd. brew install node
  3. Using npm, install Graphcool cmd. npm install -g graphcool
  4. Using npm, install Apollo cmd. npm install -g apollo
  5. Create your project.
  6. Incorporate Apollo plugins into your project. iOS | Android | ReactNative
  7. For iOS: add code generation build step for Apollo.

Later when you compiling graphql script using apollo command line, you might notice some warning that basically saying something like “the correct version of Apollo command line to use with this Apollo plugins is 1.8.x”. This is a cue for you to upgrade (or downgrade) the Apollo cmd version to the recommended one, because the version of the Apollo IDE plugin and the version of the Apollo cmd goes hand in hand. You can’t install newer Apollo cmd while using an Apollo IDE plugin that requires an older Apollo cmd version. You can check the available version here (check on the “version” tab), and the example code to install specific version of Apollo cmd using npm is: npm install -g apollo@1.8.x if the warning ask you to install Apollo cmd version 1.8.x. Without upgrading/downgrading Apollo to the correct version to go along with the plugin, your compile might fail.

Create Graphcool Server Mirror

  1. Make your account at Graphcool.
  2. Open terminal command.
  3. Change directory to your project folder.
  4. $ graphcool init server. You can change “server” into your own folder name.
  5. A folder called server will be created, with some premade files. Using terminal, change directory into that folder.

Create GraphQL Models

  1. Within the “server” folder, you can find a bunch of premade files. Of of it is types.graphql. Usually, we will put all of our schema into this file. Schema is like “table structure configuration” equivalent in SQL.
  2. Add the types.graphql into your project.
  3. Open the types.graphql using your IDE.
  4. There are two models already created there, named User and Post. Analyze the code. This should give you a good early example of how to create a model, how to create fields within model with its data type, and how to create a relationship between them.
  5. To create a field with relationship, you have to add the @relation part, following by the relationship identifier. The relationship identifier must appear exactly twice within the whole model structure, because a relationship is between one model to another model.
  6. You can make a relationship one to one, one to many, and many to many. The relation between User and Post illustrate exactly how one to many works, because Post model has one User as owner, but User model has array of Posts. You can deduct how one to one, and many to many relationship works from this.
  7. The great thing about relationship is that if you add a data on one side, then the opposite will also appear on the other side. For example, if you create a Post and set the owner Id, then that Post Id will be automatically appended on the User’s Post with that owner Id.

Deploy Your GraphQL Code Into Graphcool Server

  1. Using the terminal, change directory into the “server” folder (or whatever name you use on graphcool init).
  2. $ graphcool deploy. This will clone your graphcool schema into the server.
  3. At the first time, graphcool deployment will ask you to login to your graphcool account.
  4. It will also ask for which graphcool server you would like to use. Choose the first one.
  5. After that, it will ask for graphcool target name. I usually use my project name + “target”.
  6. And then, it will ask for graphcool service name. This is the name that will appear on graphcool console on their website. Think about it like your database name. I usually use my project name + “service”.
  7. After that, the deployment ensues, and will return your graphcool 3 APIs. The one you need to take note is the “Simple API” one, as that’s what we’re going to use.

Download Your GraphQL Schema from Graphcool using Apollo cmd

  1. The great thing about this whole GraphQL + Apollo thing is that it will make your database connection and operation strong typed. That means, you can have type checking when coding instead of trying to figure out whether you have typed the correct field or not at run time.
  2. But writing GraphQL models within your IDE (types.graphql) doesn’t make the IDE automatically receive the memo about the the strong typed checking. You need the schema in types.graphql to be converted into language that your IDE understand. That’s where Apollo comes to spotlight.
  3. Use Apollo to re-download the schema that you have cloned to the graphcool server.
  4. Using terminal, type the following command: $ apollo schema:download --endpoint:<your_graphcool_simple_API_url>
  5. This will create a file named “schema” on the current terminal directory. On iOS, this will be called schema.swift.
  6. Move schema file into your project root folder. In iOS, this is *not* referring to the directory where your *.xcproject or *.xcworkspace resides. But, in the folder where your info.plist resides.

Generate API File

  1. Compile your project.
  2. If everything goes well, the project will be compiled successfully, and a new file (in iOS named API.swift) will appear in the same directory as schema file.
  3. Add the API file to your project.
  4. This API file is what enables the strong type checking on your project. This API file will be recreated every time you hit the compile. But right now, the API is empty because you haven’t write any single graphql function.

Start Writing GraphQL Functions

  1. Create a new .graphql file in your project.
  2. Within this file, you can begin with either query syntax, or mutation syntax. Query syntax is for you to retrieve data, while mutation syntax is for you to make changes to the data (while also get returned affected data as well).
  3. Read here for GraphQL query and mutation tutorial.
  4. You can try to fiddle around with queries and mutations using Graphcool playground. It’s even equipped with autocomplete!
  5. One thing that you should note that writing queries and mutations within the playground differ than writing queries and mutations in the IDE, mainly because in the playground, you do not have external sources of data to put into your queries/mutations. You hardcoded everything into the script. While in the IDE, you will want to supply the data from your controller into the queries/mutations before fire them to the server. For that, you need to learn that you can give your query/mutation a name, along with passing parameters, which name usually prefixed with $ sign. This is the guide for it for iOS | Android | ReactNative.
  6. After you have written your queries/mutations, you can compile your project. If everything goes correctly, you will see some code magically appears on your API file. You then can use classes created in the file to fire queries/mutations within your own native code with strong type checking.

Some Patterns in Composing GraphQL Queries and Mutations

  • Let’s use the original data model User and Post created by Graphcool init server.
  • If you want to query one object from a table using its ID, call its table name. Ex: user (id: "your_id") { id, name }.
  • If you want to query all objects from a table, call all + table name + “s” (plural form). Ex: allUsers { id, name }.
  • If you want to query all objects from a table, then filter it, add filters to the parameter. Ex: allUsers (filter { name: "your_name_data" }) { id, name }. Read more about filter here.
  • If you want to create a new object into a table, add create + table name. Ex: createUser (name: "John Doe") { id, name }. You don’t need to supply ID field, as it’s automatically created by default.
  • If you want to update existing object data, add update + table name. Ex: updateUser (id: "id_object_to_be_updated", name: "Jane Doe") { id, name }.
  • If you want to append relationship connection into existing relationship array, use add + table name + field name + “Id” + “s”. Ex: addUserPostsIds (userId: "user_id", postId: "post_id") { User { id, name } }.
  • If you want to delete an object from a table, add delete + table name. Ex: deleteUser (id: "id_object_to_be_deleted_here") { id, name }.
  • If you want to remove relationship connection, use remove + table name + field name + “Id” + “s”. Ex: removeUserPostsIds (userId: "user_id", postId: "post_id") { User { id, name } }

This post is far from complete, and just serve as quick reference point for me. Hope this can help you as well. If you have a question, feel free to leave comment. I’ll help you if I can.

Leave a comment