Using the Craft CMS "headless" with the GraphQL API
Tags: craftcms, graphql, frontend
Published: 2020-03-23 21:10:06

---
title: Using the Craft CMS "headless" with the GraphQL API
published: true
date: 2020-01-20 05:00:00 UTC
tags: craftcms,graphql,frontend
canonical_url: https://nystudio107.com/blog/using-the-craft-cms-graphql-api-on-the-frontend
---

# Using the Craft CMS “headless” with the GraphQL API

### Craft CMS 3.3 added a GraphQL lay­er that gives your web­site a for­mal­ized, struc­tured API out of the box. Here’s how to use GraphQL + Craft CMS as a ​“head­less” CMS

Andrew Welch / [nystudio107](https://nystudio107.com)

![Craft cms graphql database](https://nystudio107-ems2qegf7x6qiqq.netdna-ssl.com/img/blog/_1200x675_crop_center-center_82_line/craft-cms-graphql-database.jpg)

## GraphQL & Craft CMS

This arti­cle explores cod­ing pat­terns you might find use­ful when work­ing with Craft CMS’s GraphQL API via real-world exam­ples, and also why you might want to use GraphQL to begin with.

GraphQL describes itself with the fol­low­ing pithy tagline:

<aside>
                                A query lan­guage for your <span>API</span>
                            </aside>

And that’s exact­ly what it is. It’s a neu­tral lay­er that sits on top of what­ev­er API lay­er you have, from data­bas­es like MySQL, Post­gres, Mon­go, etc. to cus­tom built solutions.

In August 2019, Pix­el & Ton­ic added GraphQL to [Craft CMS 3.3](https://craftcms.com/blog/craft-33), and vast­ly improved it in Craft CMS 3.4.

Pri­or to this, we relied on Mark Huot’s [CraftQL plu­g­in](https://plugins.craftcms.com/craftql) for GraphQL, as dis­cussed in the [Using Vue­JS + GraphQL to make Prac­ti­cal Mag­ic](https://dev.to/gaijinity/using-vuejs-graphql-to-make-practical-magic-1520-temp-slug-9813575) article.

Should you use Mark’s CraftQL plu­g­in or should you use Craft CMS’s first-par­ty GraphQL implementation?

Unless you need muta­tions (the abil­i­ty to change data in the Craft CMS back­end via GraphQL), using the Craft CMS first-par­ty GraphQL imple­men­ta­tion in Craft 3.3 or lat­er is the way to go.

Craft CMS’s first-par­ty GraphQL API does­n’t cur­rent­ly sup­port muta­tions, but it does offer a robust, per­for­mant data source for head­less Craft CMS.

## Why use GraphQL?

As a web devel­op­er, you’d use GraphQL if you were writ­ing a fron­tend that is sep­a­rate from the back­end. You’d be using Craft CMS as a ​“head­less” CMS for its excel­lent con­tent author­ing experience.

Per­haps you’re writ­ing the fron­tend in a frame­work like [React](https://reactjs.org/), [Vue.js](https://vuejs.org/), [Svelte](https://svelte.dev/), or one of the frame­works that lay­ers on top of them like [Next.js](https://nextjs.org/), [Nuxt.js](https://nuxtjs.org/), [Gats­by](https://www.gatsbyjs.org/), [Grid­some](https://gridsome.org/), or [Sap­per](https://sapper.svelte.dev/).

Or per­haps you’re jump­ing on the [JAM­stack](https://jamstack.org/) band­wag­on, and just need a self-host­ed CMS like Craft CMS to man­age your content.

<aside>
                                If you need a way to get data out of Craft <span>CMS</span>, GraphQL is a great way to do it
                            </aside>

Or maybe the project has an iPhone app that needs to com­mu­ni­cate with a con­tent man­age­ment sys­tem on the back­end for data.

In those cas­es, you don’t have access to [Twig](https://twig.symfony.com/) or the [Ele­ment Queries](https://docs.craftcms.com/v3/dev/element-queries/) to inter­act with Craft CMS and your data, but you still want to reap the ben­e­fits of Craft CMS’s won­der­ful & flex­i­ble con­tent author­ing experience.

You could write a cus­tom API for Craft CMS using the [Ele­ment API](https://github.com/craftcms/element-api), but that can be a sig­nif­i­cant amount of work, and you’ll end up with some­thing bou­tique, rather than an indus­try standard.

## Enter the GraphQL

This is where GraphQL for Craft CMS excels. By virtue of cre­at­ing your con­tent mod­els in Craft CMS, you auto­mat­i­cal­ly get a GraphQL API to access it, with no extra work on your part.

![Enter the dragon graphql](https://nystudio107-ems2qegf7x6qiqq.netdna-ssl.com/img/blog/_1200x675_crop_center-center_82_line/enter-the-dragon-graphql.jpg)

It’s also self-doc­u­ment­ing, and strict­ly typed. You don’t need to define the [GraphQL schemas](https://graphql.org/learn/schema/), because you’ve already implic­it­ly done that in Craft.

It just works.

You just need to be using Craft CMS ​“Pro” edi­tion, and you’ll see GraphQL in your CP, and you can imme­di­ate­ly start explor­ing the GraphQL API using the explor­er (which is pro­vid­ed by a fron­tend tool called [GraphiQL](https://github.com/graphql/graphiql)):

![Craft cms graphql explorer graphiql 2x](https://nystudio107-ems2qegf7x6qiqq.netdna-ssl.com/img/blog/_1200x757_crop_center-center_100_line/craft-cms-graphql-explorer-graphiql@2x.png)

While it’s beyond the scope of this arti­cle to teach you GraphQL (there are many [great resources online](https://www.google.com/search?q=learning+graphql&oq=learning+graphql) for that), there are a few things to note here:

- In the upper-left pane, is the GraphQL query spec­i­fy­ing what we’re searching
- In the low­er-left pane are vari­ables we pass into the query, in JSON format
- The mid­dle pane is the data returned from the GraphQL end­point as a result of our query
- To the right pane is a search­able, doc­u­ment­ed schema reference

The fun thing about using this GraphQL explor­er is that you can learn by just pok­ing around.

You can press **Option-Space­bar** at any time for a list of auto-com­plet­ed items that can appear in any giv­en con­text. You can also use the Doc­u­men­ta­tion Explor­er to see your entire schema.

Com­bined with the offi­cial [Craft CMS GraphQL API doc­u­men­ta­tion](https://docs.craftcms.com/v3/graphql.html), you can get pret­ty far just by explor­ing around in the GraphQL Explorer.

## The Way of the GraphQL

Before we dive into some queries in JavaScript, I have a few tips I’d like to pass along to you to make your life with GraphQL easier.

![Bruce lee nunchucks game of death graphql](https://nystudio107-ems2qegf7x6qiqq.netdna-ssl.com/img/blog/_1200x675_crop_center-center_82_line/bruce-lee-nunchucks-game-of-death-graphql.jpg)

One nice fea­ture of the Craft CMS imple­men­ta­tion of GraphQL is that it has a caching lay­er for your queries. While this is nor­mal­ly great for per­for­mance rea­sons, when you’re devel­op­ing a site, you real­ly want it off to avoid poten­tial­ly deal­ing with cached results.

You can do this via the <kbd>enableGraphQlCaching</kbd> set­ting in your <kbd>config/general.php</kbd> file:

```

<?php
/**
 * General Configuration
 *
 * All of your system's general configuration settings go in here. You can see a
 * list of the available settings in vendor/craftcms/cms/src/config/GeneralConfig.php.
 *
 * @see \craft\config\GeneralConfig
 */

return [
    // Craft config settings from .env variables
    'enableGraphQlCaching' => (bool)getenv('ENABLE_GQL_CACHING'),
];

```

Here I set it to an [Envi­ron­ment Vari­able](https://docs.craftcms.com/v3/config/environments), but you can set it to <kbd>true</kbd> or <kbd>false</kbd> direct­ly if you prefer.

Craft CMS also has a [headless­Mode](https://docs.craftcms.com/v3/config/config-settings.html#headlessmode) set­ting. This is intend­ed for sit­u­a­tions where Craft CMS will nev­er be used to ren­der any con­tent on the frontend.

Due to lim­i­ta­tions in how this works in Craft CMS 3.3, I rec­om­mend leav­ing it set to <kbd>false</kbd>, since ele­ments lack URIs in the 3.3 imple­men­ta­tion of <kbd>headlessMode</kbd>. This caus­es many plu­g­ins to not work prop­er­ly, and oth­er unde­sired behavior.

How­ev­er, Pix­el & Ton­ic has [made improve­ments](https://github.com/craftcms/cms/issues/4520#issuecomment-531040417) to how the <kbd>headlessMode</kbd> set­ting works in Craft CMS 3.4, so you can set it to <kbd>true</kbd> if you want Craft CMS to nev­er ren­der con­tent, and sim­ply be a data/​API provider via GraphQL.

Some­thing many peo­ple aren’t aware of is that you can use GraphQL in Twig if you want to:

```

{# Set the GraphQL query #}
{% set query %}
query organismsQuery($needle: String!)
{
    entries(section: "organisms", search: $needle, orderBy: "title") {
        title,
        slug,
        id
    }
}
{% endset %}

{# Set the variables to pass into the query #}
{% set variables = {
    'needle': 'Botulism'
} %}

{# Query the data via Twig! #}
{% set data = gql(query, variables) %}

{% dd data %}

```

The <kbd>gql()</kbd> Twig fil­ter was added in [Craft CMS 3.3.12](https://github.com/craftcms/cms/blob/develop/CHANGELOG-v3.md#added-5). Why would you ever want to do such a thing?

Usu­al­ly, you would­n’t. You’d just use [Ele­ment Queries](https://docs.craftcms.com/v3/dev/element-queries/) instead… but it can be a nice way to exper­i­ment and play around with queries in a familiar/​comfortable environment.

In fact, it ham­mers home a very impor­tant con­cep­tu­al point with GraphQL in Craft CMS:

<aside>
                                In Craft <span>CMS</span>, GraphQL queries map to Ele­ment Queries
                            </aside>

GraphQL is a thin-ish lay­er in Craft CMS that han­dles map­ping from a GraphQL queries to Ele­ment Queries. It works in both directions:

- The GraphQL schema is derived from the under­ly­ing Craft CMS Sec­tions, Ele­ment con­tent mod­els, etc.
- GraphQL queries are inter­nal­ly mapped to Ele­ment Queries, which are then executed

The rea­son this is an impor­tant con­cept is that if you want to fig­ure out how to do some­thing in GraphQL, **fig­ure out how to do it via an Ele­ment Query first, and then work your way back­wards**.

So it can then be handy to use <kbd>gql()</kbd> in Twig, because you can write your Ele­ment Query as you nor­mal­ly would. Get it work­ing the way you want it to, and then con­struct & test the anal­o­gous GraphQL query in the same place.

Final­ly, if you’re using Php­Storm, check out the [GraphQL Schema Auto-Com­ple­tion with Php­Storm](https://dev.to/gaijinity/graphql-schema-auto-completion-with-phpstorm-5ekm-temp-slug-8314156) arti­cle for bliss­ful auto-com­plete query writ­ing in your code.

## Con­troller of Fury

I men­tioned ear­li­er that you get a GraphQL API with­out hav­ing to do any work with Craft CMS. While this is true, hav­ing a lit­tle [cus­tom con­troller](https://www.yiiframework.com/doc/guide/2.0/en/structure-controllers) as part of your site mod­ule can be helpful.

![Bruce lee firsts of fury graphql](https://nystudio107-ems2qegf7x6qiqq.netdna-ssl.com/img/blog/_1200x675_crop_center-center_82_line/4937/bruce-lee-firsts-of-fury-graphql.jpg)

I always have a site mod­ule as part of my Craft CMS setups, as dis­cussed in the [Enhanc­ing a Craft CMS 3 Web­site with a Cus­tom Mod­ule](https://dev.to/gaijinity/enhancing-a-craft-cms-3-website-with-a-custom-module-33g1-temp-slug-8101978) article.

You always start with no cus­tom code, but inevitably you end up need­ing a lit­tle piece here or there. And if you have a mod­ule in place already, it makes adding this in real­ly easy.

In our case, we want a cus­tom con­troller that our fron­tend can ping to:

- <kbd>actionGetCsrf()</kbd> — get the cur­rent [CSRF token](https://www.yiiframework.com/doc/guide/2.0/en/security-best-practices#avoiding-csrf) to val­i­date POST request submissions
- <kbd>actionGetGqlToken()</kbd> — get a par­tic­u­lar GraphQL token for access permissions
- <kbd>actionGetFieldOptions()</kbd> — get the options in a Drop­down field in Craft CMS

POST requests are used to send data from the web­site along to an end­point. While we could use GET for sim­ple requests like <kbd>actionGetGqlToken()</kbd>, we need to send data to oth­er end­points like <kbd>actionGetFieldOptions()</kbd>, so we might as well use POST for all requests.

Here’s what our cus­tom con­troller looks like:

```

<?php
/**
 * Site module for Craft CMS 3.x
 *
 * An example module for Craft CMS 3 that lets you enhance your websites with a
 * custom site module
 *
 * @link https://nystudio107.com/
 * @copyright Copyright (c) 2019 nystudio107
 */

namespace modules\sitemodule\controllers;

use Craft;
use craft\web\Controller;

use yii\web\Response;

/**
 * @author nystudio107
 * @package SiteModule
 * @since 1.0.0
 */
class SiteController extends Controller
{
    // Constants
    // =========================================================================

    const GQL_TOKEN_NAME = 'Site GQL Token';

    // Protected Properties
    // =========================================================================

    protected $allowAnonymous = [
        'get-csrf',
        'get-gql-token',
        'get-field-options',
    ];

    // Public Methods
    // =========================================================================

    /**
     * @inheritdoc
     */
    public function beforeAction($action): bool
    {
        // Disable CSRF validation for get-csrf POST requests
        if ($action->id === 'get-csrf') {
            $this->enableCsrfValidation = false;
        }

        return parent::beforeAction($action);
    }

    /**
     * @return Response
     */
    public function actionGetCsrf(): Response
    {
        return $this->asJson([
            'name' => Craft::$app->getConfig()->getGeneral()->csrfTokenName,
            'value' => Craft::$app->getRequest()->getCsrfToken(),
        ]);
    }

    /**
     * @return Response
     */
    public function actionGetGqlToken(): Response
    {
        $result = null;
        $tokens = Craft::$app->getGql()->getTokens();
        foreach ($tokens as $token) {
            if ($token->name === self::GQL_TOKEN_NAME) {
                $result = $token->accessToken;
            }
        }

        return $this->asJson([
            'token' => $result,
        ]);
    }

    /**
     * Return all of the field options from the passed in array of $fieldHandles
     *
     * @return Response
     */
    public function actionGetFieldOptions(): Response
    {
        $result = [];
        $request = Craft::$app->getRequest();
        $fieldHandles = $request->getBodyParam('fieldHandles');
        foreach ($fieldHandles as $fieldHandle) {
            $field = Craft::$app->getFields()->getFieldByHandle($fieldHandle);
            if ($field) {
                $result[$fieldHandle] = $field->options;
            }
        }

        return $this->asJson($result);
    }
}

```

While this cus­tom con­troller isn’t nec­es­sary for using your GraphQL end­point, it does make the expe­ri­ence a bit nicer. We grab the CSRF token, and send that CSRF token along with fur­ther requests, to allow Yii2 to val­i­date the data submissions.

## Schemas & Tokens

GraphQL in Craft CMS has a con­cept of Schemas and Tokens:

- **Schemas**  — schemas you can think of these as per­mis­sions, in a way, in that they define what parts of the under­ly­ing CraftCMS con­tent you want exposed

![Craft cms graphql schemas 2x](https://nystudio107-ems2qegf7x6qiqq.netdna-ssl.com/img/blog/_1200x759_crop_center-center_100_line/craft-cms-graphql-schemas@2x.png)

- **Tokens**  — tokens are they ​“keys” that you pass along with your GraphQL queries, and they link to a schema

![Craft cms graphql tokens 2x](https://nystudio107-ems2qegf7x6qiqq.netdna-ssl.com/img/blog/_1200x759_crop_center-center_100_line/craft-cms-graphql-tokens@2x.png)

So what I do is:

1. Get the CSRF token for the cur­rent session
2. Use that CSRF to obtain a spe­cif­ic GraphQL token used for API access
3. Use that GraphQL token in all GraphQL request to the endpoint

In many cas­es, you won’t need to do this because you’ll just have one Pub­lic Schema that defines your GraphQL API. But if you want to poten­tial­ly have vary­ing lev­els of access, you’d cre­at­ed mul­ti­ple tokens and use them to what schema you can use.

If you just want to use the spe­cial Pub­lic Schema, you don’t need any token at all. Just don’t send a bear­er token down with your GraphQL queries, and it’ll just use what­ev­er schema is defined in Pub­lic Schema.

**N.B.:** In our case, we want pub­lic access to do the data. The CRSF and GraphQL tokens are just for light­weight auth, it is not treat­ed as a locked down ​“secret” for auth’ing. For that you’d want some­thing like [JSON Web Tokens](https://jwt.io/) (JWT), check out the [Craft JWT Auth](https://plugins.craftcms.com/craft-jwt-auth) plugin.

## Con­troller & GraphQL XHRs

Let’s get into some JavaScript that we use to com­mu­ni­cate with our cus­tom con­troller end­points, and also the Craft CMS GraphQL endpoint.

First here is a lit­tle <kbd>xhr.js</kbd> helper to con­fig­ure and exe­cute gener­ic XHRs:

```

// Configure the XHR api endpoint
export const configureXhrApi = (url) => ({
    baseURL: url,
    headers: {
        'X-Requested-With': 'XMLHttpRequest'
    }
});

// Execute an XHR to our api endpoint
export const executeXhr = async(api, variables, callback) => {
    // Execute the XHR
    try {
        const response = await api.post('', variables);
        if (response.data) {
            callback(response.data);
        }
    } catch (error) {
        console.error(error);
    }
};

```

The <kbd>X-Requested-With: XMLHttpRequest</kbd> head­er lets Craft CMS know that this is an ​“AJAX” request, which can affect how the request is processed.

Here’s how we get the CSRF from our cus­tom con­troller endpoint:

```

import axios from 'axios';
import { configureXhrApi, executeXhr } from '../utils/xhr.js';

const CSRF_ENDPOINT = '/actions/site-module/site/get-csrf';

// Fetch & commit the CSRF token
export const getCsrf = async({commit, state}) => {
    const api = axios.create(configureXhrApi(CSRF_ENDPOINT));
    let variables = {
    };
    // Execute the XHR
    await executeXhr(api, variables, (data) => {
        commit('setCsrf', data);
    });
};

```

The above func­tion is a [Vuex Action](https://vuex.vuejs.org/guide/actions.html), but Vuex is just used as a con­ve­nient place to store data. It’s not impor­tant that you use Vuex your­self to get some­thing out of the exam­ples pre­sent­ed here.

The code is just cre­at­ing an [Axios](https://github.com/axios/axios) instance, exe­cut­ing the XHR, and stash­ing the returned CSRF data for future use.

We just use Axios here as opposed to some­thing like [Apol­lo Client](https://www.apollographql.com/docs/react/) just because all we real­ly need is a light­weight way to com­mu­ni­cate with­out GraphQL end­point. We could also use the built-in [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), but Axios han­dles some edge-case sit­u­a­tions and brows­er com­pat­i­bil­i­ty for us.

Then this is how we get the GraphQL token:

```

import axios from 'axios';
import { configureGqlApi, executeGqlQuery } from '../utils/gql.js';

// Fetch & commit the GraphQL token
export const getGqlToken = async({commit, state}) => {
    const api = axios.create(configureXhrApi(TOKEN_ENDPOINT));
    let variables = {
        ...(state.csrf && { [state.csrf.name]: state.csrf.value }),
    };
    // Execute the XHR
    await executeXhr(api, variables, (data) => {
        commit('setGqlToken', data);
    });
};

```

Once again, this is a Vuex Action, but it does­n’t have to be. The impor­tant part is that it’s using the CSRF we obtained ear­li­er, and send­ing that along with a request for our GraphQL token, which it then saves for future use.

The funky <kbd>...(state.csrf &amp;&amp; { [state.csrf.name]: state.csrf.value }),</kbd> line deserves some expla­na­tion. It’s using the [JavaScript Spread Syn­tax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) to add a key/​value pair to the <kbd>variables</kbd> object.

But it’s doing it in a con­di­tion­al way, using the behav­ior of the [JavaScript && Log­i­cal Oper­a­tor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_Operators) to only spread the <kbd>{ [state.csrf.name]: state.csrf.value }</kbd> object into <kbd>variables</kbd> only if <kbd>state.csrf</kbd> is truthy.

This works because JavaScript will return the object if <kbd>state.csrf</kbd> is truthy, and if not, it’ll return <kbd>state.csrf</kbd> itself, and the <kbd>…</kbd> spread syn­tax is smart enough to know not to spread <kbd>null</kbd>, so it spread noth­ing into <kbd>variables</kbd>.

Final­ly we have some helper JavaScript in <kbd>gql.js</kbd> (very sim­i­lar to the <kbd>xhr.js</kbd> above) which con­fig­ures and cre­ates an Axios instance for query­ing Craft’s GraphQL endpoint:

```

// Configure the GraphQL api endpoint
export const configureGqlApi = (url, token) => ({
    baseURL: url,
    headers: {
        'X-Requested-With': 'XMLHttpRequest',
        ...(token && { 'Authorization': `Bearer ${token}` }),
    }
});

// Execute a GraphQL query by sending an XHR to our api endpoint
export const executeGqlQuery = async(api, query, variables, callback) => {
    // Execute the GQL query
    try {
        const response = await api.post('', {
            query: query,
            variables: variables
        });
        if (callback && response.data.data) {
            callback(response.data.data);
        }
        // Log any errors
        if (response.data.errors) {
            console.error(response.data.errors);
        }
    } catch (error) {
        console.error(error);
    }
};

```

This just adds an addi­tion­al a [Bear­er Token](https://www.oauth.com/oauth2-servers/differences-between-oauth-1-2/bearer-tokens/) to the head­er which Craft CMS will use to link to the schema that the request will have per­mis­sion to access, and it adds some error log­ging spe­cif­ic to the GraphQL implementation.

## A Sim­ple Query

Let’s look at a sim­ple query that uses the infra­struc­ture we’ve described above:

```

export const organismsQuery =
    `
query organismsQuery($needle: String!)
{
    entries(section: "organisms", search: $needle, orderBy: "title") {
        title,
        slug,
        id
    }
}
`;

```

This is the same query we looked at in the GraphQL Explor­er pre­vi­ous­ly, which is exe­cut­ed as follows:

```

import axios from 'axios';
import { configureGqlApi, executeGqlQuery } from '../utils/gql.js';

const GRAPHQL_ENDPOINT = '/api';

// Fetch & commit the Organisms array from a GraphQL query
export const getOrganisms = async({commit, state}) => {
    const token = state.gqlToken ? state.gqlToken.token : null;
    const api = axios.create(configureGqlApi(GRAPHQL_ENDPOINT, token));
    let variables = {
        needle: 'useInSearchForm:*'
    };
    // Execute the GQL query
    await executeGqlQuery(api, organismsQuery, variables, (data) => {
        if (data.entries) {
            commit('setOrganisms', data.entries);
        }
    });
};

```

This is once again a Vuex Action, which uses the GraphQL token we’ve already obtained, and pass­es in <kbd>useInSearchForm:*</kbd> as a search para­me­ter in <kbd>needle</kbd>.

This is look­ing for a lightswitch field in Craft CMS with the han­dle <kbd>useInSearchForm</kbd>, so that it’ll only return entries from the <kbd>organisms</kbd> sec­tion that have that lightswitch on.

This returns data that looks like this:

```

[
    {
        "title": "Bacillus cereus",
        "slug": "bacillus-cereus",
        "id": "10226"
    },
    {
        "title": "Bacterial toxin",
        "slug": "bacterial-toxin",
        "id": "14472"
    },
]

```

## Query­ing a Sin­gle Thing

Nor­mal­ly all of your GraphQL queries will return an array of data, even if you’re only ask­ing for one thing. While this con­sis­ten­cy is nice, there are times when you real­ly only ever want one thing returned.

In Craft CMS 3.4, sin­gu­lar ver­sions of all of the queries were made available:

- <kbd>assets()</kbd> → <kbd>asset()</kbd>
- <kbd>categories()</kbd> → <kbd>category()</kbd>
- <kbd>entries()</kbd> → <kbd>entry()</kbd>
- <kbd>globalSets()</kbd> → <kbd>globalSet()</kbd>
- <kbd>tags()</kbd> → <kbd>tag()</kbd>
- <kbd>users()</kbd> → <kbd>user()</kbd>

This is anal­o­gous to the <kbd>.all()</kbd> → <kbd>.one()</kbd> meth­ods used on Ele­ment Queries.

So we can lever­age this for our queries where we only ever want one thing returned, so we don’t have to do ugly <kbd>[0]</kbd> array syntax:

```

export const outbreakDetailQuery =
    `
query outbreakDetailQuery($slug: [String])
{
    entry(section: "outbreaks", slug: $slug) {
        title,
        url,
        slug,
        ...on outbreaks_outbreaks_Entry {
            summary,
            beginningDate,
            states,
            country,
            hasTest,
            testResults,
            productSubjectToRecall,
            totalIll,
            numberIllByCaseDefinitionKnown,
            probableIll,
            possibleIll,
            confirmedIll,
            hospitalized,
            numberHospitalized,
            anyDeaths,
            numberOfDeaths,
            recallLinks {
                col1
                url
            },
            reportReferenceLinks {
                col1
                url
            },
            brands {
                title
            },
            locations {
                title
            },
            organisms {
                title
            },
            tags {
                title
            },
            vehicles {
                title
            }
        }
    }
}
`;

```

This rather large query exem­pli­fies the GraphQL mind­set, which is that you need to spec­i­fy **all** of the data that you want returned. This is unlike Ele­ment Queries, where by default you get all of the data back.

Here’s what it looks like exe­cut­ing this query:

```

import axios from 'axios';
import { configureGqlApi, executeGqlQuery } from '../utils/gql.js';

const GRAPHQL_ENDPOINT = '/api';

// Fetch & commit an Outbreak detail from a GraphQL query
export const getOutbreakDetail = async({commit, state}) => {
    const token = state.gqlToken ? state.gqlToken.token : null;
    const outbreakSlug = state.outbreakSlug || null;
    const api = axios.create(configureGqlApi(GRAPHQL_ENDPOINT, token));
    let variables = {
        slug: outbreakSlug
    };
    // Execute the GQL query
    await executeGqlQuery(api, outbreakDetailQuery, variables, (data) => {
        if (data.entry) {
            commit('setOutbreakDetail', data.entry);
        }
    });
};

```

This code is almost exact­ly iden­ti­cal to the code we used to for <kbd>getOrganisms()</kbd>, except that we pass in a <kbd>slug</kbd> to look for in our <kbd>entry()</kbd> query rather than a <kbd>search</kbd> parameter.

Here’s what the data returned from this query looks like:

```

{
  "title": "2017 Multistate Outbreak of Salmonella Infantis Linked Mangoes (Suspected)",
  "url": "http://outbreakdatabase.test/outbreaks/2017-multistate-outbreak-of-salmonella-infantis-linked-mangoes-suspected",
  "slug": "2017-multistate-outbreak-of-salmonella-infantis-linked-mangoes-suspected",
  "summary": "In the summer of 2017 federal, state and local health officials investigated an outbreak of Salmonella Infantis. The suspected vehicle of transmission was mangoes. Forty eight outbreak associated cases were reported by 14 states. Reported and estimated illness onset dates ranged from June 30, 2017 to August 31, 2017. Among 42 cases with available information, there were 15 reported hospitalizations. No deaths were reported. \nThe cluster investigation was assigned CDC 1708MLJFX-1.",
  "beginningDate": "2017-06-01T07:00:00+00:00",
  "states": [
    "CA",
    "IL",
    "IN",
    "MI",
    "MN",
    "NJ",
    "NY",
    "NC",
    "OH",
    "OK",
    "TX",
    "WA",
    "WI"
  ],
  "country": "us",
  "hasTest": "yes",
  "testResults": "JFXX01.0010",
  "productSubjectToRecall": "yes",
  "totalIll": 48,
  "numberIllByCaseDefinitionKnown": "yes",
  "probableIll": null,
  "possibleIll": null,
  "confirmedIll": 48,
  "hospitalized": "yes",
  "numberHospitalized": 15,
  "anyDeaths": "",
  "numberOfDeaths": null,
  "recallLinks": [
    {
      "col1": "",
      "url": ""
    }
  ],
  "reportReferenceLinks": [
    {
      "col1": "",
      "url": ""
    }
  ],
  "brands": [],
  "locations": [
    {
      "title": "Retail"
    }
  ],
  "organisms": [
    {
      "title": "Salmonella"
    }
  ],
  "tags": [
    {
      "title": "salmonellosis"
    },
    {
      "title": "salmonella"
    },
    {
      "title": "mangoes"
    },
    {
      "title": "infantis"
    }
  ],
  "vehicles": [
    {
      "title": "Mangoes"
    }
  ]
}

```

## Dynam­ic Para­me­ter Queries

But what if we’re doing some­thing more com­pli­cat­ed, like a faceted search, where we want to nar­row down the search cri­te­ria based on a series of option­al search para­me­ters from the user such as shown in this video:

Pri­or to Craft CMS 3.4, you could­n’t do this via the GraphQL API. But Craft CMS 3.4 added two key fea­tures to make it possible

- It’s now pos­si­ble to query for ele­ments by their cus­tom field val­ues via GraphQL. ([#5208](https://github.com/craftcms/cms/issues/5208))
- It’s now pos­si­ble to fil­ter ele­ment query results by their relat­ed ele­ments using rela­tion­al fields’ ele­ment query params (e.g. <kbd>publisher(100)</kbd> rather than <kbd>relatedTo({targetElement: 100, field: 'publisher'}))</kbd>. ([#5200](https://github.com/craftcms/cms/issues/5200))

These are both huge in terms of mak­ing the GraphQL API flex­i­ble, so hat’s off to Andris for mak­ing it happen.

This allows us to con­struct a dynam­ic query like this:

```

export const outbreaksQuery = (additionalParams) => {
    let queryAdditionalParams = '';
    let entryAdditionalParams = '';
    additionalParams.forEach((item) => {
        queryAdditionalParams += `, $${item.fieldName}: [QueryArgument]`;
        entryAdditionalParams += `, ${item.fieldName}: $${item.fieldName}`;
    });
    return `
    query outbreaksQuery($needle: String!${queryAdditionalParams})
    {
        entries(section: "outbreaks", search: $needle${entryAdditionalParams}) {
            title,
            url,
            slug,
            ...on outbreaks_outbreaks_Entry {
                summary,
                beginningDate,
                vehicles {
                    title
                },
                organisms {
                    title
                },
                tags {
                    title
                }
            }
        }
    }
    `;
};

```

Note that this is a func­tion, not a sim­ple returned [tem­plate lit­er­al](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) as in the pre­vi­ous examples.

This allows us to dynam­i­cal­ly add para­me­ters to our query based on what­ev­er has been pushed into the <kbd>additionalParams</kbd> array.

So the base query looks like this:

```

query outbreaksQuery($needle: String!)
{
    entries(section: "outbreaks", search: $needle) {
        title,
        url,
        slug,
        ...on outbreaks_outbreaks_Entry {
            summary,
            beginningDate,
            vehicles {
                title
            },
            organisms {
                title
            },
            tags {
                title
            }
        }
    }
}

```

…and the vari­ables we pass in look like this:

```

{
    needle: "vomit"
}

```

If the user then also adds in an organ­ism to search on (which in our case is a relat­ed entry in the Craft CMS back­end), the query will look like this:

```

query outbreaksQuery($needle: String!, $organisms: [QueryArgument])
{
    entries(section: "outbreaks", search: $needle, organisms: $organisms) {
        title,
        url,
        slug,
        ...on outbreaks_outbreaks_Entry {
            summary,
            beginningDate,
            vehicles {
                title
            },
            organisms {
                title
            },
            tags {
                title
            }
        }
    }
}

```

…and the vari­ables we pass in look like this:

```

{
    needle: "vomit",
    organisms: "4425"
}

```

The <kbd>4425</kbd> num­ber is the ele­ment ID of the relat­ed organ­ism entry in the Organ­isms sec­tion. It could also be an array of IDs, or any­thing else you’d nor­mal­ly pass in as a rela­tion­al field­’s ele­ment query params.

This tech­nique works for an arbi­trary num­ber of addi­tion­al faceted search cri­te­ria, which gives the user quite a bit of pow­er in the search form.

Here’s the Vuex Action code that imple­ments it:

```

import axios from 'axios';
import { configureGqlApi, executeGqlQuery } from '../utils/gql.js';

const GRAPHQL_ENDPOINT = '/api';

// Push additional params
const pushAdditionalParam = (state, dataFieldName, dbFieldName, additionalParams) => {
    let fieldValue = state.searchForm ? state.searchForm[dataFieldName] || '' : '';
    if (fieldValue.length) {
        // Special case for fields
        if (dbFieldName === 'states') {
            // As per https://docs.craftcms.com/v3/checkboxes-fields.html#querying-elements-with-checkboxes-fields
            fieldValue = `*"${fieldValue}"*`
        }
        additionalParams.push({
            fieldName: dbFieldName,
            fieldValue: fieldValue,
        });
    }
};

// Fetch & commit the Outbreaks array from a GraphQL query
export const getOutbreaks = async({commit, state}) => {
    const token = state.gqlToken ? state.gqlToken.token : null;
    const keywords = state.searchForm ? state.searchForm.keywords || '*' : '*';
    // Construct the additional parameters
    let additionalParams = [];
    for (const [key, value] of Object.entries(additionalParamFields)) {
        pushAdditionalParam(state, key, value, additionalParams);
    }
    // Configure out API endpoint
    const api = axios.create(configureGqlApi(GRAPHQL_ENDPOINT, token))
    // Construct the variables object
    let variables = {
        needle: keywords,
    };
    additionalParams.forEach((item) => {
        variables[item.fieldName] = item.fieldValue;
    });
    // Execute the GQL query
    await executeGqlQuery(api, outbreaksQuery(additionalParams), variables, (data) => {
        if (data.entries) {
            commit('setOutbreaks', data.entries);
        }
    });
};

```

This <kbd>pushAdditionalParam()</kbd> func­tion just does a lit­tle mag­ic to map from the name of a prop­er­ty in our Vue com­po­nent to the name of the field in the database.

Then it spe­cial-cas­es for the <kbd>states</kbd> field, which is Check­box­es field in Craft CMS. To query for an item in a Check­box­es field, you need to use the for­mat <kbd>'*"foo"*'</kbd>.

As per what we dis­cussed pre­vi­ous­ly, we fig­ured this out by [look­ing up how to do it in an Ele­ment Query](https://docs.craftcms.com/v3/checkboxes-fields.html#templating), and then using that in our GraphQL query.

Then the <kbd>getOutbreaks()</kbd> func­tion then just dynam­i­cal­ly builds the <kbd>additionalParams</kbd> array and <kbd>variables</kbd> object, which then is passed along to our query.

The data returned from this query looks like this:

```

[
  {
    "title": "1997 Botulism After Consumption of Home-Pickled Eggs, Illinois",
    "url": "http://outbreakdatabase.test/outbreaks/1997-botulism-after-consumption-of-home-pickled-eggs-illinois",
    "slug": "1997-botulism-after-consumption-of-home-pickled-eggs-illinois",
    "summary": "On November 23, 1997, a previously healthy man became nauseated, vomited, and complained of abdominal pain. During the next 2 days, he developed double vision, difficult movement of joints, and respiratory impairment. He was hospitalized and placed on mechanical ventilation. His physical examination confirmed multiple cranial nerve abnormalities, including extraocular motor palsy and diffuse flaccid paralysis. Botulism was diagnosed, and antibotulinum toxin was administered. His blood serum demonstrated the presence of type B botulinum toxin. A food history revealed no exposures to home-canned products; however, the patient had eaten pickled eggs that he had prepared seven days before his symptoms began. The patient recovered after a prolonged period of supportive care. \n\nThe pickled eggs were prepared using a recipe that consisted of hard-boiled eggs, commercially prepared beets and hot peppers, and vinegar. The intact hard-boiled eggs were peeled and punctured with toothpicks then combined with the other ingredients in a glass jar that closed with a metal screw-on lid. The mixture was stored at room temperature and occasionally was exposed to sunlight. \n\nCultures revealed Clostridium botulinum type B, and type B toxin was detected in samples of the pickled egg mixture, the pickling liquid, beets, and egg yolk. The commercially sold peppers contained no detectable toxin or Clostridium botulinum bacteria. Beets from the original commercial containers were not available. The pH of the pickling liquid was 3.5 (i.e., adequate to prevent C. botulinum germination and toxin formation, however, the pH of egg yolk, although not tested for the investigation, is normally 6.8., conducive for bacteria growth and toxin production. Inadequate acidification and lack of refrigeration enhanced the risk of bacterial contamination of this home-prepared food.",
    "beginningDate": "1997-11-01T08:00:00+00:00",
    "vehicles": [
      {
        "title": "Eggs, Pickled eggs"
      }
    ],
    "organisms": [
      {
        "title": "Botulism"
      }
    ],
    "tags": [
      {
        "title": "c.+botulinum"
      },
      {
        "title": "clostridium+botulinum"
      },
      {
        "title": "c.+bot."
      }
    ]
  }
]

```

## Tap­ping Out

Hope­ful­ly these real-world exam­ples of using Craft CMS’s GraphQL API in ​“head­less” CMS setups has been help­ful to you!

![Bruce lee sunset graphql](https://nystudio107-ems2qegf7x6qiqq.netdna-ssl.com/img/blog/_1200x675_crop_center-center_82_line/bruce-lee-sunset-graphql.jpg)

Craft CMS is an excel­lent choice if you want to com­bine a great con­tent author­ing expe­ri­ence on the back­end with a ​“head­less” CMS that serves up data to a fron­tend via a GraphQL API.

If you’re a plu­g­in or cus­tom mod­ule devel­op­er, there are also some oth­er nice new fea­tures in Craft CMS 3.4 for GraphQL:

- Plu­g­ins can now mod­i­fy the GraphQL schema via <kbd>craft\gql\TypeManager::EVENT_DEFINE_GQL_TYPE_FIELDS</kbd>
- Plu­g­ins can now mod­i­fy the GraphQL per­mis­sions via <kbd>craft\services\Gql::EVENT_REGISTER_GQL_PERMISSIONS</kbd>

This allows for great flex­i­bil­i­ty in terms of extend­ing the exist­ing Craft CMS GraphQL API.

Hap­py querying!

## Further Reading

_If you want to be notified about new articles, follow [nystudio107](https://twitter.com/nystudio107) on Twitter._

<small>Copyright ©2020 nystudio107. Designed by nystudio107</small>