Uploading files in Brightspot Content Management API

This guide will explain how to upload files to Brightspot records via CMA GraphQL mutation APIs.

Prerequisites for uploading a file
For endpoint configuration, see Custom Content Management API development and Hello Content Management API.

Introduction to uploading a file
Being that the official GraphQL spec does not currently support upload mutations, the CMA implements a popular community extension to the specification: GraphQL multipart request specification.

Background to uploading a file
Consider the following Image content class that will store our file and be configured as a mutable entry field on our endpoint:

package com.company;

import com.psddev.cms.db.Content;
import com.psddev.dari.util.StorageItem;

public class Image extends Content {

    private StorageItem file;

    public StorageItem getFile() {
        return file;
    }

    public void setFile(StorageItem file) {
        this.file = file;
    }
}

Example of uploading a file

<!DOCTYPE>
<html lang="en">
    <head>
        <title>CMA StorageItem Upload Example</title>
    </head>
    <body>
        <input type="file" id="file-selector">
        <script>
            (() => {
                const fileSelector = document.getElementById('file-selector');
                fileSelector.addEventListener('change', (event) => {
                    
                    const file = event.target.files[0];
                    const query = 'mutation MyMutation($file: Upload!) { com_company_ImageSave( diffs: [{ ' +
                        'com_company_ImageDiff: { file: { file: $file } } }] ) { file {  path  } }}'
                    const variables = { file: null }
                    const operations = { query, variables }
                    const map = { 0: ['variables.file'] }

                    const formData = new FormData();
                    formData.append('operations', JSON.stringify(operations))
                    formData.append('map', JSON.stringify(map))
                    formData.append('0', file, file.name)

                    fetch('<API_ENDPOINT_URL>', {
                        method: 'POST',
                        headers: {
                            'x-api-key': '<API_KEY>'
                        },
                        body: formData,
                    })
                    .then(response => response.json())
                    .then(responseData => {
                        console.log('Success:', responseData);
                        document.body.innerHTML = '<div>Upload Successful!</div>'
                    })
                    .catch((error) => {
                        console.error('Error:', error);
                    });
                });
            })();
        </script>
    </body>
</html>