GraphQL Project Setup

Setting up a new project with GraphQL

In order to connect a new project to the GraphQL client, you will need the CMBox Instance Url, the API token, and the target Repository ID.

Create an env for storage

It is best practice to keep your token inside an env to prevent it from leaking. You can also store your CMBox instance Url in the env and reference them both inside your project as variables.

this.url = import.meta.env.CMBOX_INSTANCE_URL;
this.token = import.meta.env.CMBOX_API_TOKEN;

Creating the GraphQL connector

You can then use the target repository id to connect to the GraphQL API.

const graphQL = new GraphQLClient(`${this.url}/api/graphql/${repo.CACHE_ROOT}`, {headers:{Authorization:`Bearer ${this.token}`}});

Once you have the graphQL client generated, you can create your own query and settings variables to retrieve items from the CMBox repository.

Pre-generated Query Example

In this example, getQuery takes in the GraphQL client and autogenerates a query that will retrieve all fields in the GraphQL Schema.

Set variables

For the initial page load, the variables will be set to some default values so that all content will be returned.

let variables = {
    "slug": null,
    "settings": {
        "limit": itemLimit,
        "start": 0,
        "filters": null,
        "query": null,
        "sort":"updatedDate:DESC"
    }
}

updateVariables is a function that handles user input on the front end via input boxes or select boxes to narrow down the content that is being queried. For example, if the user selects a different sorting option, it could replace updatedDate:DESC with name:ASC to sort in alphabetical order rather than timestamp.

For this example, the word test was placed in the search bar and the query was executed with query: null getting replaced with query: 'test'

variables = {
    "slug": null,
    "settings": {
        "limit": itemLimit,
        "start": 0,
        "filters": null,
        "query": 'test',
        "sort":"updatedDate:DESC"
    }
}

Execute request

const query = await getQuery(graphQL);
const queryResponse = await this.graphQL.request(this.query, updateVariables(variables));

Response

{
  "data": {
    "items": {
      "count": 6,
      "items": [
        {
          "name": "test1",
          "id": "ITEM_619493D4F2C7489990A2C76DAAC3C8E1",
          "slug": "upload_1714767180679_test1"
        },
        {
          "name": "test2",
          "id": "ITEM_7F71D42B0515434092AD8ADDF70E8CBC",
          "slug": "video_1714767166490_test2"
        },
        {
          "name": "test3",
          "id": "ITEM_02ECFC34A23A4478A7879C52801FBC96",
          "slug": "video_1714767147786_test3"
        },
        {
          "name": "test4",
          "id": "ITEM_6A83DFD2277C4288954AAC9C6A472C61",
          "slug": "image_1714766498197_test4"
        },
        {
          "name": "test5",
          "id": "ITEM_4C3116E71BF04995A91DF06CD7145B6C",
          "slug": "file_1714766444134_test5"
        },
        {
          "name": "test6",
          "id": "ITEM_829C2ACED55744CBB5BE3361C414CB27",
          "slug": "file_1714766434942_test6"
        }
      ]
    }
  }
}

Custom Query Example

If you wanted to create a custom query for specific response data, you can swap out the generated query for your own GraphQL variable, which you can test with the explorer or postman.

Create custom query

let query = `
query Query($settings: QuerySettings) {
  items(settings: $settings) {
    count
    items {
      ... on Image {
        name
        id
        slug
      }
    }
  }
}`

Set variables

let variables = {
    "slug": null,
    "settings": {
        "limit": itemLimit,
        "start": 0,
        "filters": null,
        "query": null,
        "sort":"updatedDate:DESC"
    }
}

Execute request

const queryResponse = await this.graphQL.request(query, variables);

Response

{
    "data": {
        "items": {
            "count": 1,
            "items": [
                {
                    "name": "customQuery",
                    "id": "ITEM_FC349528FD4845A0BF443DD21771AB7B",
                    "slug": "upload_1714514638752_customQuery"
                }
            ]
        }
    }
}