GraphQL tools for getting started with Contentful

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.

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. 

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. 

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.