Creating and updating records in Brightspot Content Management API
This guide will explain how to create and update Brightspot records via CMA GraphQL mutation APIs.
Prerequisites for using the CMA
For endpoint configuration, see Custom Content Management API development and Hello Content Management API.
Introduction to the CMA
In the Content Management API, value differences for the proposed state are used to mutate an object. Passing in state differences, rather than an entire state object, accurately represents how users input data into Brightspot.
Background to the CMA
Consider the following record classes where setters and getters are omitted for brevity:
public class Foo extends Record {
private String title;
private Integer number;
private List<Integer> numbers;
private boolean flag;
@Recordable.Embedded
private Bar bar;
private Baz baz;
}@Recordable.Embedded
public class Bar extends Record {
private String barTitle;
}public class Baz extends Record {
private String bazTitle;
}Following is a portion of the schema, concerned with mutation types and based on the aforementioned record classes, with Foo configured as a mutable entry field:
type Mutation {
com_company_FooSave(diffs: [com_company_FooDiffInput], id: DiffId, toolUser: RefId): com_company_Foo
}
input com_company_FooDiffInput {
com_company_BarDiff: com_company_BarInput
com_company_FooDiff: com_company_FooInput
id: DiffId
}
input com_company_FooInput {
bar: DiffId
baz: RefId
flag: Boolean
number: Int
numbers: [Int]
title: String
}
input com_company_BarInput {
barTitle: String
}Inputs:
-
id: diff ID to match the main diff input for the record creation or update -
diffs: every embedded record updated by the mutation requires a diff input with its relevant changes -
toolUser: user ID, username, or email so history for the record can be updated appropriately
DiffId inputs can be an existing UUID, new UUID, or even a random identifier. Existing UUIDs are necessary for updating existing records while new UUIDs create new records. The random identifier feature allows callers to create new records with invalid UUIDs, such as “1,” to simplify record creation. Random identifiers are matched up and converted to new, valid UUIDs upon record creation.
RefId inputs are utilized for pointing to non-embedded records via their ID.
CMA examples
Below are a few examples of typical create and update CMA save mutations. They are run against a schema with Foo and Baz configured as mutable entry fields. Since Baz is not an embedded record on Foo, and instead referenced by Foo, it needs to be an entry field in order to retrieve more data than _id and _type.
Record creation
The following example shows the creation of a Foo record. Notice that a non-embedded Baz record, already in existence, is assigned to it.
Query
mutation MyMutation {
com_company_FooSave(id: "1", toolUser: "jentile@brightspot.com",
diffs: [
{
id: "1",
com_company_FooDiff: {
title: "Hello World!"
flag: true
number: 1
numbers: [2, 3]
baz: "00000177-72e6-d6fd-a97f-76f6002a0000"
}
}
]
) {
_id
title
flag
number
numbers
baz {
_id
bazTitle
}
}
}Response
{
"data": {
"com_company_FooSave": {
"_id": "00000177-72ea-d6fd-a97f-76fa15700000",
"title": "Hello World!",
"flag": true,
"number": 1,
"numbers": [2, 3],
"baz": {
"_id": "00000177-72e6-d6fd-a97f-76f6002a0000",
"bazTitle": "Hello Human!"
}
}
}
}Here’s an example where embedded record data is supplied during creation. An embedded Bar record is created and assigned to the new Foo record.
Query
mutation MyMutation {
com_company_FooSave(id: "1", toolUser: "jentile@brightspot.com",
diffs: [
{
id: "1",
com_company_FooDiff: {
bar: "2"
}
},
{
id: "2",
com_company_BarDiff: {
barTitle: "Hello Atom!"
}
}
]
) {
_id
bar {
_id
barTitle
}
}
}Response
{
"data": {
"com_company_FooSave": {
"_id": "00000177-72ea-d6fd-a97f-76fa15700000",
"bar": {
"_id": "00000177-72ea-d6fd-a97f-76fa15700001",
"barTitle": "Hello Atom!"
}
}
}
}Record update
The following example shows an update to the existing Foo record from the previous example. Notice that the embedded Bar record does not need to be reassigned to the Foo record, yet its value can still be updated. Additionally, a different non-embedded Baz record is assigned.
Query
mutation MyMutation {
com_company_FooSave(id: "00000177-72ea-d6fd-a97f-76fa15700000", toolUser: "jentile@brightspot.com",
diffs: [
{
id: "00000177-72ea-d6fd-a97f-76fa15700000",
com_company_FooDiff: {
title: "Hello Universe!"
baz: "00000177-72f2-d6fd-a97f-76f281400000"
}
},
{
id: "00000177-72ea-d6fd-a97f-76fa15700001",
com_company_BarDiff: {
barTitle: "Hello Quark!"
}
}
]
) {
_id
title
bar {
_id
barTitle
}
baz {
_id
bazTitle
}
}
}Response
{
"data": {
"com_company_FooSave": {
"_id": "00000177-72ea-d6fd-a97f-76fa15700000",
"title": "Hello Universe!",
"bar": {
"_id": "00000177-72ea-d6fd-a97f-76fa15700001",
"barTitle": "Hello Quark!"
},
"baz": {
"_id": "00000177-72f2-d6fd-a97f-76f281400000",
"bazTitle": "Hello Sentient Being!"
}
}
}
}