GraphQL tools for getting started with Contentful

Published on December 20, 2022

GraphQL tools for getting started with Contentful

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.

If you’re new to using GraphQL with Contentful, we have put together a handy cheat sheet to get you started. In this guide, we highlight the most commonly used GraphQL tools and features. 

First things first, GraphQL is a query language that provides developers with the flexibility to retrieve data from APIs. In particular, the GraphQL Content API supports our Content Delivery API (CDA) and our Content Preview API (CPA). 

A GraphQL schema comes with every Contentful space, which is based on the query language’s content types. You can find out more information on endpoint filtering capabilities, schema generation process, and error codes in the reference guide.

There are some fantastic educational resources available, which you can check out below:

With all this in mind, let’s dive into the need-to-knows.

GraphQL tools and access

There are many tools that allow you to use GraphQL with Contentful. Here's a selection to get you started.

1. Basic Contentful GraphQL API

Typically when you are using the GraphQL API in your code, you will use the following URL to request content:

https://graphql.contentful.com/content/v1/spaces/[SPACE_ID]. 

The content you receive from this URL is the same as the content you would receive when using the Contentful Delivery API. 

2. GraphiQL tool

You also may use GraphiQL, an IDE tool by going to this URL:

 https://graphql.contentful.com/content/v1/spaces/[SPACE_ID]/explore?access_token=[CDA_API_TOKEN]. 

This tool allows you to build GraphQL queries easily in the browser. 

GraphQL

You can access your space ID and Content Delivery API token in your Contentful space settings.

3. GraphQL Playground App

Within Contentful, we also offer the GraphQL Playground App. It is similar to GraphiQL in that it allows you to build GraphQL queries, but the main benefit is that it allows you to do so within the Contentful web app and also automatically will connect to your Contentful space so there is no need to insert your API token or Contentful space ID.

Playground App

Contentful GraphQL queries

Keep in mind that in order to access draft content, you'll need to use your Contentful Preview API. Here are some of the most used Contentful GraphQL queries you’ll want to know.

Single entry query

Here’s how to retrieve a single entry.

Which returns the following:

Collection query

This is how you can retrieve multiple entries.

Which returns the following:

Preview query

Finally, use the following code, should you wish to include draft entries.

Reference queries

For single reference queries; query a reference field that only accepts a specific entry type.

Which returns the following:

When a reference field is created in a content type, there is the option to limit what types of entries can be referenced. The screenshot below is an example of what the validation would look like for a field where this query should be used. 

GraphQL

Various reference types

Query a reference field that accepts multiple entry types. 

In the reference field validation, if multiple entry types are selected as shown below, in your query, you must specify which entry type you would like to return. 

GraphQL

For queries that have many references, it’s possible that you might hit query complexity limits. To avoid this, you can add limits to your queries to lower the complexity cost.

GraphQL basics

Reference queries

You can reuse queries by passing down variables. In this example, this query might be used on a blog to show all of the posts for a certain author. Instead of writing a new query for every author, the same query can be used as the author’s name changes. 

Step 1: Define variable

Step 2: Use variable in query

Named queries

You can provide unique query names to organize multiple queries.

Aliases

You can provide alternative names, or aliases, for query results to avoid conflicts when fetching from the same field or collection.

Fragments

These are reusable field groups that can be shared between multiple fields and queries.

Which returns the following:

Directives

You can include or skip a field in a query based on a variable value. 

Step 1: Create variable

Step 2: Use variable with directives

Request

Here’s an example of how to request data using GraphQL with JavaScript.

Variables

You can create dynamic queries and add type safety.

Step 1: Define variables

Step 2: Use variable in a query

Step 3: Use variable in an API request

You can check out our blog for a detailed walkthrough of how to utilize variables in GraphQL in requests.

Wrapping up

Visit our developer portal for even more guides, tips and tricks. The portal also houses developer blog posts, videos, and tutorials.

Check out our Developer Showcase to see what developers have built with Contentful and to submit your own projects.

As always, feel free to contact us on Slack or Twitter to let us know how we can better support your awesome builds.

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.

Related articles

Pagination is about splitting content into pages for easier display and navigation in a website or app. Learn four ways to implement pagination in React.
Guides

React pagination tutorial: 4 ways with full code examples

September 22, 2024

Just like a password, an API key is a code that helps secure your API (Application Programming Interface). Learn more on the Contentful blog.
Guides

What is an API key?

February 3, 2023

A tutorial on GraphQL pagination, including cursor and offset-based methods. Examples integrate real-world GraphQL APIs into a React application.
Guides

GraphQL pagination: Cursor and offset tutorials

October 28, 2024

Contentful Logo 2.5 Dark

Ready to start building?

Put everything you learned into action. Create and publish your content with Contentful — no credit card required.

Get started