Was this page helpful?

GraphQL quick start guide

With this guide you will learn how to get started with Contentful's GraphQL API. It will help you setup a sample app which showcases all the elements involved in making queries to the GraphQL endpoint.

Note: if you're looking for the reference documentation, please head to the reference documentation.


Before we start make sure that:

  • You have a Contentful account.
  • You have installed node at least at version 8.

Using the Contentful example app content model

In this section we will setup a new space, download and run a example application using the GraphQL Delivery API.

1. Install the contentful-cli and login to Contentful

npm install -g contentful-cli
contentful login

2. Create a new space which we will use for this guide

contentful space create --name "GraphQL example space"

3. Use this newly created space for future command executions

contentful space use

4. Scroll through the list and pick the space created at step 2 by pressing Enter.

5. Initialize the space with the example application data

contentful space seed --template the-example-app

6. Download the boilerplate code that we will use to interact with the GraphQL API.

contentful boilerplate

7. Pick the boilerplate named 'GraphQL JS Boilerplate'

8. Unzip the boilerplate package and install the dependencies.

unzip -d boilerplate-graphql-js boilerplate-graphql-js.zip
cd boilerplate-graphql-js/
npm install
npm start

The output of the last command will be:

Fetching and displaying all courses details ...

Here are the results of your query:
Course Hello Contentful has the following lessons:
  - Lesson APIs
  - Lesson Content model
  - Lesson Content management
  - Lesson Summary
Course Hello SDKs has the following lessons:
  - Lesson SDK basics
  - Lesson Fetch all entries
  - Lesson Fetch draft content
  - Lesson Serve localized content
  - Lesson Summary

We're done!

Check out the code to try some more queries!

Or explore your space using GraphiQL:

Read more about available functionality in our reference documentation:

You can now open the boilerplate-graphql-js/index.js file and familiarize yourself with the queries that are performed there. As an exercise you could now change the GraphQL queries and run the tool again to see how the output changes.

Here are some changes that can be done:

  • Change the locale used in the queries to the german one (de-DE). See the reference documentation about query localization
  • Extend the details of each entry with its id. See the reference documenation about the entry schema structure
  • Get the url of the linked image in the Lesson > Image content type. See the reference documentation about the asset schema

Using your own space

You can also try the GraphQL API using the content model and entries from one of your existing spaces.

To try this, you can use the GraphiQL interface by opening this URL: https://cdn.contentful.com/spaces/{SPACE_ID}/graphql/alpha/explore?access_token={CDA_TOKEN}

By replacing:

  • {SPACE_ID} with your own space ID
  • {CDA_TOKEN} with a Content Delivery API access token for the space

If you followed the steps outlined in the first section of this guide, you can adapt the source code to experiment with it.

Important notes:

  • Relations between content types have to be defined using the linkContentType validation. For more information check the modelling relationships section in the reference documentation.

To learn more about the features and limitations of the GraphQL Delivery API, head to the reference documentation.

Align your content with GraphQL

Date field

We recently switched our GraphQL type for Contentfuls' Date field from a generic String to its own scalar called DateTime.

Our Management API used to allow more than just ISO 8601 formatted values to be stored - for our GraphQL Delivery API we want to leverage as much type safety as possible, though. Therefore we decided to only support ISO 8601 datetimes in the GraphQL API. With this, your queries might yield partial errors on execution time for entries that contain invalid values in Date fields.

Writing an example migration

What you'll need:

  • Our contentful-cli to execute the migration
  • Your space ID
  • A managemement token. For example a Personal Access Token generated via contentful login
  • The content type ID of the failing entries (product in our example)

Note: in case you have multiple content types with invalid date values, you can duplicate the migration and adjust the content types.

For example, a releaseDate field was created to store the specific release date of a product. Due to a mistake, by now we stored the values in the format DD.MM.YYYY, e.g. 13.05.2014. Now we want to make them ISO 8601 compliant. For simplicity UTC midnight is chosen. This implementation differs based on your use-case.

module.exports = function (migration) {
    contentType: 'product',
    from: ['releaseDate'],
    to: ['releaseDate'],
    transformEntryForLocale: function (fromFields, currentLocale) {
      const currentReleaseDate = fromFields.releaseDate[currentLocale]
      const invalidDate = Number.isNan(new Date(currentReleaseDate).getTime())

      // If we have a valid date already, return it
      if (!invalidDate) {
        return { releaseDate: currentReleaseDate }

      const [day, month, year] = currentReleaseDate.split('.').map(Number)

      const normalizedTimestamp = Date.UTC(year, month - 1, day)
      const normalizedReleaseDate = new Date(normalizedTimestamp).toISOString()

      return { releaseDate: normalizedReleaseDate };

We assume you have successfully logged in or otherwise provided the access token. If you're unsure, run this command and follow the steps there:

$ contentful login

Now run the migration file with the following command:

$ contentful space migration --space-id <SPACE_ID> ./path/to/migration.js

Once the migration finished, re-run your GraphQL query - tada! The errors are gone.

Still have questions?

Ask our team!

Next steps

Not what you’re looking for? Try our FAQ.