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:

• Introduction to GraphQL (↗)

• How to GraphQL (↗)

• Guides and Best Practices (↗)

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. 

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.

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.

Copy

Which returns the following:

Copy

Collection query

This is how you can retrieve multiple entries.

Copy

Which returns the following:

Copy

Preview query

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

Copy

Reference queries

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

Copy

Which returns the following:

Copy

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. 

Various reference types

Query a reference field that accepts multiple entry types. 

Copy

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. 

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

Copy

Step 2: Use variable in query

Copy

Named queries

You can provide unique query names to organize multiple queries.

Copy

Copy

Aliases

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

Copy

Fragments

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

Copy

Which returns the following:

Copy

Directives

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

Step 1: Create variable

Copy

Step 2: Use variable with directives

Copy

Request

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

Copy

Variables

You can create dynamic queries and add type safety.

Step 1: Define variables

Copy

Step 2: Use variable in a query

Copy

Step 3: Use variable in an API request

Copy

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.

Start building

Sign up for a free Contentful account

Use your favorite tech stack, language, and framework of your choice.

Subscribe for updates

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