Use the Contentful GraphQL API inside a GraphQL Playground

instructions.md

Use the Contentful GraphQL API inside a GraphQL Playground

The Contentful GraphQL API ships with GraphiQL by default. To get even better workflows (such as multiple tabs, speciyfing HTTP headers or work with multiple GraphQL APIs side-by-side), you can use a GraphQL Playground.

1. Get the endpoint for your Contentful GraphQL API

The endpoint of your Contentful GraphQL API has the following structure: https://cdn.contentful.com/spaces/{SPACE}/graphql/alpha/explore?access_token={CDA_TOKEN}

There are two placeholders that need to be replaced:

• SPACE: The ID of your Contentful space, e.g. 9t7hdjj3yos9
• CDA_TOKEN: The access token for the Content Delivery API of your Contentful space, e.g. 9a6ce8c14bbf5777c01e7c39a67d9bea3b491af2eb8647ca08c9ec26ba8a23b1

Opening this endpoint in a browser gives you access to GraphiQL.

2. Install the GraphQL CLI

npm install -g graphql-cli

3. Create a .graphqlconfig

The graphql playground command of the GraphQL CLI reads information from a local .graphqlconfig (which follows the graphql-config standard).

mkdir myapi
touch myapi/.graphqlconfig.yml

Now add the following contents to the newly created .graphqlconfig.yml:

projects:
  cf:
   schemaPath: contentful.graphql
   extensions:
     endpoints:
       default:
         url: https://cdn.contentful.com/spaces/{SPACE}/graphql/alpha?locale=en-US
         headers:
           Authorization: Bearer {CDA_TOKEN}

Replace {SPACE} and {CDA_TOKEN} with the values for your space ID and the access token for the Content Delivery API (as before). Here is what the result could look like:

projects:
  cf:
   schemaPath: contentful.graphql
   extensions:
     endpoints:
       default:
         url: https://cdn.contentful.com/spaces/9t7hdij3yor9/graphql/alpha?locale=en-US
         headers:
           Authorization: Bearer 9a6ce8c14abf5777c01e7c39a67d9bea3b491af2eb8647ca08c9eb26ba8a23b1

4. Open a GraphQL Playground

Run the following command in your terminal:

graphql playground

Pro tip: To get the full experience, download and install the standalone Desktop version of the GraphQL Playground from here.

5. (Optional) Download the GraphQL schema of the Contentful GraphQL API

Run the following command in your terminal:

graphql get-schema

The GraphQL CLI reads the schemaPath property from .graphqlconfig.yml, downloads the schema via an introspection query from the API and stores it in that path.