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.

Building a sample app

The app we will create on this guide can be used either with new or existing space. Before we start make sure that the following preconditions are met:

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

Starting with a new space

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
  1. Create a new space which we will use for this guide
$ contentful space create --name "GraphqQL example space"
  1. Initialize the space with the example application data
# Grab the space id returned by the previous command
$ contentful space seed --space-id SPACE_ID --template the-example-app
  1. Download the boilerplate code that we will use to interact with the GraphQL API.
# Run the following command and pick the 'GraphQL JS Boilerplate'
$ contentful boilerplate --space-id SPACE_ID
  1. Unzip the boilerplate package and install the dependencies.
$ unzip -d boilerplate-graphql-js boilerplate-graphql-js.zip
$ cd boilerplate-graphql-js/
boilerplate-graphql-js$ npm install
boilerplate-graphql-js$ 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:
https://cdn.contentful.com/spaces/{SPACE_ID}/graphql/alpha/explore?locale={LOCALE_CODE}&access_token={ACCESS_TOKEN}

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 then rerun the tool to see how the ouput 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

Starting with your own space

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

Important:

  • Relations between content types have to be defined using the linkContentType validation. For more information check the modelling relationships section in the reference documentation.
  • Content type names are used to generate the schema. For more information check the content types section in the reference documentation.

  • Install the contentful-cli and login to Contentful

$ npm install -g contentful-cli
$ contentful login
  1. Download the boilerplate app that we will use to interact with the GraphQL API.
# Run the following command and pick the 'Javascript (GraphQL) Boilerplate'
$ contentful boilerplate --space-id SPACE_ID
  1. Unzip the boilerplate package and install the dependencies.
$ unzip -d boilerplate-graphql-js boilerplate-graphql-js.zip
$ cd boilerplate-graphql-js/
boilerplate-graphql-js$ npm install
  1. Modify the boilerplate code to reflect the shape of your schema and then run it.
boilerplate-graphql-javascript$ npm start