Building a Basic GraphQL Application

Since Facebook released their GraphQL technology back in 2015, it has evolved into a wonderful query language perfectly suited for all kinds of today's API endpoints. Why?
  • Comes with a much more definite way of describing the data passed through your API.
  • Allows the client to fetch many resources in a single request, rather than forcing it to send multiple ones to different endpoints.
  • Built from the ground up so that only data requested by the client is sent back. This makes GraphQL apps react quickly even on slow mobile network connections.
Because of these advantages, it's a great alternative to REST.
Convinced? Then let's create a application that fetches data from a GraphQL endpoint!

Requirements

Before we get started, please make sure that your instance of Node is up-to-date. You should have the latest "Current" release (compare it with this). If it's not, click on the download button on the site and get yourself the newest version.
You can use this command to check the version tag of your local instance:
node -v
Once the output of the command matches the latest version on the site, go on to the next section.

Building the API

Let's start with creating a new empty directory and moving into it:
mkdir graphql-apicd graphql-api
Now let's create the project's package.json file inside that directory:
{
  "name": "graphql-api",
  "scripts": {
    "start": "micro index.js"
  }
}
The code above tells now the name of the project ("graphql-api") and also to execute the index.js file (using micro, which we'll install in the next paragraph) when the npm start command is run in your terminal or on the server.
Next, we need to install a few packages:
Run this command in your terminal to install them using npm:
npm install --save graphql micro micro-cors express-graphql
Now we need to create the index.js file and populate it with content. As the first step, load the packages:
const {buildSchema} = require('graphql')
const server = require('express-graphql')
const CORS = require('micro-cors')()
Then define the type of data provided by the API. In our case, we'll only respond with a single key named hello, holding a "Hello world" message. In turn, it will be of type String:
const schema = buildSchema(`
  type Query {
    hello: String
  }
`)
And now the value for each key of the response:
const rootValue = {
  hello: () => 'Hello world'
}
As the last line of code in the file, you need to call express-graphql, wrap it with micro-cors and export it:
module.exports = CORS(server({ schema, rootValue }))
Now you should be able to run npm start inside the directory containing the API and you should be handed a URL which will show the following when opened in a browser window:
On the first glance, it looks like an error. Well... It actually is one.
But in our case, it's a sign that you've managed to set up the code for the GraphQL API properly. Why? Because it indicates that the endpoint is able to accept data (the error comes directly from express-graphql).

Deploying the API

After we've finished building the API endpoint, we need to deploy it. Simply run this command in your terminal:
now
Once now has finished uploading the files, you'll see a URL that points to your freshly created API. We'll use this address later in the application and load some data from it.
But in the case of a real API (not used for testing purposes), you would now have to assign an alias to it.

Building the Client

Now that we have the deployment for the API endpoint in place, we need to build an application that loads the data from there and shows it to the visitor. As a framework, we'll use create-react-app, a neat way of building React apps.
Creating the project's file structure is as easy as running this command (the directory will be called "graphql-client"):
create-react-app graphql-client
Then you can start the development server by running this command:
npm start
This works because inside the package.json file, there's a script property named start defined that executes the react-scripts start command when run in the terminal or on the server.

Installing "react-apollo"

In order to make the application capable of loading data using GraphQL, we need to firstly install react-apollo, a package that provides all of the tools necessary for interacting with a GraphQL API using React.
To install it, run this command in a separate terminal tab (please ensure that you're inside the "graphq-client" directory):
npm install --save react-apollo

Adding the Communicating Interface

Once all of them have finished installing, open the index.js file inside the src directory. Now remove all the code and start fresh with loading all packages (including React) and the built-in <App/> component:
import React from 'react'
import ReactDOM from 'react-dom'

import { ApolloClient, ApolloProvider, createNetworkInterface } from 'react-apollo'

import App from './App'
Continue with creating an instance of ApolloClient and pointing it to your GraphQL server created earlier:
const client = new ApolloClient({
  networkInterface: createNetworkInterface({ uri: 'REPLACE_THIS_WITH_YOUR_API_URL' })
})
As the next step, we need to connect your client instance to the component tree. This can be done using the ApolloProvider component. Generally, it should be placed somewhere high in your view hierarchy, above all places where you need to access data.
In our case, we only have one existing component (<App/>, which was already there when we generated the application). In turn, we only need to wrap this one with the ApolloProvider component:
ReactDOM.render(
  <ApolloProvider client={client}>
    <App />
  </ApolloProvider>
  ,
  document.getElementById('root')
)

Loading Data from the GraphQL Server

Now that the interface for communicating with the API endpoint is in place, the only thing left for displaying the "Hello World" example is telling the client exactly which data to request.
Open the App.js file inside the src directory, remove its content and start with loading all packages required:
import React from 'react'
import { gql, graphql } from 'react-apollo'
Next, use gql to create the data query and assign it to a constant. This will tell react-apollo to only load the hello property (which we've defined earlier while writing the GraphQL API):
const myQuery = gql`{ hello }`
Now we only need to create the <App/> component. Let's just render a heading with the data from the API inside it:
class App extends React.Component {
  render() {
    return <h1>{this.props.data.hello}</h1>
  }
}
Because we want to use it inside the index.js file (we already loaded it there), we need to export it now. But to receive the data using the react-apollo package, we also need to wrap the component into the graphql() helper and pass the query to it:
export default graphql(myQuery)(App)
That's all for building the client!
You should now be able to access the app on the address you saw in the terminal while running the npm start command earlier. By default, it should be the following one: http://localhost:3000.
In the browser, the client should look like this:

Deploying the Client

Pat yourself on the shoulder! You've managed to build your first GraphQL API, deploy it and even create a client that pulls data from it. Isn't that cool? Absolutely!
So guess what's next! Now we'll make the client accessible from all over the world as well.
But before we can do that, we need to prepare it by installing a tiny tool of ours (named serve). Because create-react-app doesn't come with a built-in webserver that can be used in production, you need to provide your own. So let's install serve by running this command in the terminal (inside the "graphql-client" directory):
npm install --save serve
Then you need to add the now-start property to your package.json file. The command specified inside it will be run on now when the deployment is about to start.
"scripts": {
  ...
  "now-start": "serve -s ./build"
}
Now you can do the same you did for the API. Deploy the client by running this command:
now
Open the URL provided by now and you should see the "Hello world!" example again. This means that you did everything right and your first GraphQL application is online. Well done!