What is GraphQL?
GraphQL is a way of fetching data. It’s an alternative to REST API, and many call it the “new” way of getting data. These are my top reasons for using GraphQL:
- Fetches only the data you need
- Does not require you to study docs for hours to learn the API specifics
- Allows you to combine multiple data sources in a single query
This is what a simple GraphQL query looks like:
content in this context is a codename of a content type.
It fetches titles, teasers, and slugs of 3 articles for a website homepage, as that’s all we need for that page. The response is minimalistic JSON:
So, where are we on the “no need to read docs” point? How do we actually know that there are articles and that they each have a title and a teaser?
GraphQL comes with a schema. It’s a map of all your content, and it’s a great source of information for GraphiQL or GraphQL Playground (works online) that allows you to build and test your queries. Let’s take a look at it.
Build and test GraphQL queries
When you enter the playground, expand the Schema tab on the right. You’ll see the generated schema of your project:
But that’s not the best part. On the left, write this query syntax:
And hit CTRL+SPACE (or OPTION+SPACE on Mac) with your cursor within the curly brackets. You’ll see an IntelliSense popup that shows you all available data:
We don’t really need to know the complete project structure or understand the API specifics. We can navigate through the available items and mark the data and properties we need for our use case. Curly brackets expand the current item, parentheses let you filter, limit, and order. The play button executes the query and shows you the fetched data:
Try it out with your project and build a query that’s useful for your project.
Now that we have our query, how can we use it in our JS projects?
With REST API, we were used to leveraging third-party tools like Axios, Request, or Fetch (which is now widely available in browsers) to compose and execute the queries. With GraphQL, we need to use Apollo Client:
We create the client and configure it to use the right endpoint:
Note: If you’re using React and need the client on many pages throughout your app, you can use the
ApolloProvider component that wraps your React app and lets you use React hook
useQuery to fetch data.
Then, you can start fetching data with your GraphQL queries:
The client returns data in JSON, so you can directly use it in your components:
GraphQL vs. REST API
So what’s better, GraphQL or REST API? Let’s do a quick pros and cons list:
I’m afraid there’s no clear winner. As always, it depends on your project and its requirements.
GraphQL was originally created to streamline data fetching from multiple sources—to allow developers to focus on their implementation rather than spend half of their days reading docs. And it does that perfectly. GraphQL can make a real difference in data fetching simplicity for large projects that require content from Kontent, products from Shopify, user data from the PostgreSQL database, and so on. If you’re interested in this topic, you can check out my article about Apollo.
For smaller projects where we mainly work with content from a single source—the headless CMS—GraphQL is nothing new. We’ve already seen it in Gatsby or Gridsome, and we’ve learned that it helps with development speed a lot. If you manage to keep your queries at a reasonable size, there are not many disadvantages. Especially now when Kontent features a native GraphQL endpoint hosted on the global Fastly CDN.