GraphQL has become popular recently and is likely to replace the Rest API. In this tutorial, we will use the Apollo Client to communicate with GitHub's GraphQL API. We will integrate Apollo Client with ReactJS, but you can also use it with other platforms (VueJS, Angular, etc).
This tutorial does not cover how to start a React project, but you can use create-react-app to get started.
Once we have the React application ready to run, the next step is to install the required modules.
Installing Modules
The following line installs all the required modules.
npm i -S apollo-client-preset react-apollo graphql-tag graphql
Now we can provide our component with a client.
Providing a Client to a Component
You can provide a client anywhere in the React component hierarchy. However, it is always a good practice to provide the component by wrapping your entire application with the client.
Index.js
Above you can see that we defined the uri for GitHub and also used a specific token for the headers. You should use your own token generated from GitHub. So don't forget to replace it in YOUR_TOKEN.
You can check this link how to get an API Token.
For this example, we defined the API token on the client side. However, you should not reveal your API token publicly. Therefore, it is always good to keep it on the server abstracted from the client side.
Note that we have wrapped the component with ApolloProvider and used the client variable we created for the client prop.
GraphiQL Application
Before diving into queries, I want to point out that there is a very useful tool called GraphiQL for testing your GraphQL queries. Before continuing, make sure you have downloaded it.
Once you open GraphiQL, you need to configure GraphQL Endpoint and HTTP Headers.
GraphQL Endpoint: https://api.github.com/graphql
Header Name: Authorization
Header Value: Bearer YOUR_TOKEN
Of course, you should replace YOUR_TOKEN with your own token. Don't forget to include the Bearer before your token when defining the header value.
If you don't want to download an application, you can also use GraphQL API Explorer for GitHub.
GraphQL Queries
Unlike a REST API with multiple endpoints, the GraphQL API only has one endpoint and only gets what your query defines.
The GitHub GraphQL API documentation provides more information.
Additionally, the best part of the GraphiQL application is that it gives you access to the query documentation within the application. You can see the sidebar on the right called Docs.
GraphiQL — Side Bar Docs
Let's start with the simplest query:
query {
viewer {
login
}
}
This query returns the login information of the viewer. In this case, the viewer is you since you used your own API token.
In this tutorial, I will not give detailed information about queries. You can always refer to the documentation and try queries in GraphQL tools to see if you are getting the correct data.
Let's use the following query for the rest of the tutorial.
query ($name: String!) {
search(query: $name, last: 10, type: REPOSITORY) {
edges {
node {
... on Repository {
id
name
description
url
}
}
}
}
}
This query searches for the last 10 repositories that match the specific input string, which we will define in our application.
It returns the id, name, description, and URL of each result.
Using GraphQL Query in a React Component
We need to import two modules below into our React component to define the query within the component and then pass the results to the component as props.
import gql from "graphql-tag";
import { graphql } from "react-apollo";
Here we assign our query to a constant variable, but we have not yet defined the name parameter.
GraphQL Query
Now we wrap our component with graphql HOC (Higher Order Component) to define the query parameters, execute the query, and then pass the result as props to our component.
graphql HOC
Below is the final version of our component.
App.js
Note that we do not export the actual App component, but the wrapped component, which is AppWithData.
Check the Data in the Console
Let's go ahead and add console.log(this.props) to your component's render method.
When you check your browser's console, you will see that there are two object logs.
Within each object, you will see the data property. This is provided to our component through the graphql HOC.
Notice that the first log has the property loading: true within data and the second log has loading: false and a new object called search, which is exactly the information we wanted to get.
Display the Data
Let's write some JSX to display the obtained data.
Since the search object is not initially there, we cannot attempt to render it directly. Therefore, we first need to check if the data and the search object are ready to be used.
To do that, we will simply use the loading information provided within the data property.
If loading is true, we simply render the text Loading, otherwise the data itself.
Display Data
I used the ternary operator ?: for basic inline conditional expressions. If loading is true, we show Loading and if it is false, we use the map function to iterate through our data array to display the information within ul and li elements.
This is just a basic example. You can use a regular if-else statement and return different results for your render method.
App.js Final
You can check the repository apollo-client-with-react, clone it to your computer, and play around.
PS. Don't forget to replace the token variable with your own GitHub API token.
Conclusion
We covered how to get started with Apollo Client for React. We installed the required modules, set up the client, and then provided it to our component at the top of the component hierarchy. We learned how to quickly test GraphQL queries before implementing them in our real application. Finally, we integrated the query into a React component and displayed the obtained data.
I hope this was helpful and/or taught you something new!
