DatoCMS optionally supports optimistic locking. When updating an existing record, you can specify its current version within the appropriate meta property. DatoCMS compares this version with the current version stored to ensure that a client doesn't overwrite a record that has since been updated. If the version changed in-between, DatoCMS would reject the update with a 422 STALE_ITEM_VERSION error.

For more information, take a look at the Javascript examples.

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const itemId = "4235";
8

9
  const item = await client.items.update(itemId, {
10
    // we just pass the field that we want to change
11
    title: "[EDIT] My first blog post!",
12
  });
13

14
  console.log(item);
15
}
16

17
run();

1
{
2
  id: "hWl-mnkWRYmMCSTq4z_piQ",
3
  title: "My first blog post!",
4
  content: "Lorem ipsum dolor sit amet...",
5
  category: "24",
6
  image: {
7
    alt: "Alt text",
8
    title: "Image title",
9
    custom_data: {},
10
    focal_point: null,
11
    upload_id: "20042921",
12
  },
13
  meta: {
14
    created_at: "2020-04-21T07:57:11.124Z",
15
    updated_at: "2020-04-21T07:57:11.124Z",
16
    published_at: "2020-04-21T07:57:11.124Z",
17
    first_published_at: "2020-04-21T07:57:11.124Z",
18
    publication_scheduled_at: "2020-04-21T07:57:11.124Z",
19
    unpublishing_scheduled_at: "2020-04-21T07:57:11.124Z",
20
    status: "published",
21
    is_current_version_valid: true,
22
    is_published_version_valid: true,
23
    current_version: "4234",
24
    stage: null,
25
  },
26
  item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" },
27
}

1
import { ApiError, buildClient } from "datocms-client";
2

3
// Make sure the API token has access to the CMA, and is stored securely
4
const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
5

6
async function updateRecordByIncrementingCounter(itemId) {
7
  // first we get the record we want to update
8
  const record = await client.items.find(itemId);
9

10
  try {
11
    // now we increment the counter value, passing the current version
12
    // to enable optimistic-locking
13
    client.items.update(itemId, {
14
      counter: record.counter + 1,
15
      meta: { current_version: record.meta.current_version },
16
    });
17

18
    console.log("Done!");
19
  } catch (e) {
20
    // if we get a STALE_ITEM_VERSION error, this means that the
21
    // the record changed in-between the find and update operations, so we have
22
    // to fetch the latest version of the record and try again
23
    if (e instanceof ApiError && e.findError("STALE_ITEM_VERSION")) {
24
      console.log("Stale version, retrying...");
25
      return updateRecordByIncrementingCounter();
26
    }
27

28
    throw e;
29
  }
30
}
31

32
await updateRecordByIncrementingCounter("1230982");

1
> node example.js
2

3
Stale version, retrying...
4
Stale version, retrying...
5
Done!

Working with block records

Block records live inside of Modular Content, Structured Text and Single Block fields, which require different data structures as their value: while Modular Content is simply an array of blocks, Single Block accept only one block. Structured Text accepts a Structured text document, which in turn might contain a number of block nodes interspersed with textual content.

We’ll get to some detailed examples for both fields below, but the general idea that applies to both of them is that to preserve the atomicity property of ACID transactions, DatoCMS prohibits you from creating/editing/deleting blocks directly; you always need to add/edit/remove blocks by performing a create/update operation on the record that embeds them, so:

If you want to add a block to a particular field, you need to add to the existing field value the new “fragment” related to the new block;
If you want to edit a block that’s already present in the field, you need to pass the whole field value and replace only the “fragment” related to such block, while keeping the rest unchanged;
If you want to remove a block that’s already present in the field, you need to pass the whole field value and only remove the "fragment” related to such block, while keeping the rest unchanged.

Depending on the endpoints you're going to use, the “fragment” representing the block can be simply its ID, or a full JSON API object:

Endpoint	HTTP request blocks representation	HTTP response blocks representation
GET /items	N/A	ID
GET /items?nested=true	N/A	JSON resource object
GET /item/	N/A	ID
GET /item/ ?nested=true	N/A	JSON resource object
POST /items	JSON resource object	ID
PUT /items/	ID or JSON resource object	ID

During an update operation, to reference a block:

when you want to make some changes to the content of a specific block, you pass the complete JSON
resource object (complete with its existing id);
when you want to add a totally new block, you pass the complete JSON
resource object (with no ID of course, as it’s a new object);
when you don’t want to make any change to an existing block, you can pass just the block ID (the update operation will be faster this way, as it won’t have to process it).

When updating a block, you use destructuring to combine existing and updated content. Use Array.map() to go through the existing blocks one by one, keeping their current ordering.

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  // These define what to update
8
  const recordId = "A4gkL_8pTZmcyJ-IlIEd2w"; // The record's unique ID
9
  const fieldWithBlocks = "modular_content_field"; // Which record field are the blocks in?
10
  const blockId = "ToBApjdYQaCgeFJxp_ty0A"; // ID of the block we want to update ("Example block #1")
11
  const blockFieldsToUpdate = {
12
    // Inside the block, what are we updating?
13
    title: "Example block #1 (Updated title)", // Update the title
14
  };
15

16
  // Get the current record
17
  const currentRecord = await client.items.find(recordId, {
18
    nested: true, // Also fetch the content of nested blocks, not just their IDs
19
  });
20

21
  console.log(
22
    "Current record before the update, with nested blocks",
23
    JSON.stringify(currentRecord, null, 2),
24
  );
25

26
  // Build the update before sending it
27
  const currentBlock = currentRecord[fieldWithBlocks].find(
28
    (block) => block.id === blockId,
29
  ); // The block's existing content
30
  const updatedBlock = {
31
    ...currentBlock, // Keep its existing metadata
32
    attributes: {
33
      ...currentBlock.attributes, // Keep existing attributes that we didn't update
34
      ...blockFieldsToUpdate, // Inject updated fields
35
    },
36
  };
37
  const updatedFieldWithBlocks = currentRecord[fieldWithBlocks].map(
38
    (
39
      block, // Map through existing blocks so we keep their ordering
40
    ) =>
41
      block.id === updatedBlock.id
42
        ? updatedBlock //  If it's the block we want to update, inject the updated data
43
        : block.id, // Otherwise, just provide the old block's ID and the API will know to keep it unchanged
44
  );
45

46
  // Perform the update by actually sending what we built to the API
47
  const updatedRecord = await client.items.update(recordId, {
48
    [fieldWithBlocks]: updatedFieldWithBlocks, // The record field to update
49
    // We don't have to specify the other fields. The API will keep them the same.
50
  });
51

52
  console.log(
53
    "Updated record. Only block IDs are returned, not their content.",
54
    updatedRecord,
55
  );
56
}
57

58
run();

1
// Current record before the update, with nested blocks
2
{
3
  id: "A4gkL_8pTZmcyJ-IlIEd2w",
4
  type: "item",
5
  title: "This is an example record with blocks in a modular content field",
6
  modular_content_field: [
7
    {
8
      type: "item",
9
      attributes: {
10
        title: "Example block #1",
11
      },
12
      relationships: {
13
        item_type: {
14
          data: {
15
            id: "cR-9e-65SNat84KEs5M22w",
16
            type: "item_type",
17
          },
18
        },
19
      },
20
      id: "ToBApjdYQaCgeFJxp_ty0A",
21
    },
22
    {
23
      type: "item",
24
      attributes: {
25
        title: "Example block #2",
26
      },
27
      relationships: {
28
        item_type: {
29
          data: {
30
            id: "cR-9e-65SNat84KEs5M22w",
31
            type: "item_type",
32
          },
33
        },
34
      },
35
      id: "YGrrPYrkSNaq-dBaP7aSaQ",
36
    },
37
  ],
38
  item_type: {
39
    id: "LvTZuGYRTQO9aBVk0g35Jw",
40
    type: "item_type",
41
  },
42
  creator: {
43
    id: "627975",
44
    type: "organization",
45
  },
46
  meta: {
47
    created_at: "2024-09-06T17:19:59.151+01:00",
48
    updated_at: "2024-10-03T00:41:15.497+01:00",
49
    published_at: "2024-10-03T00:41:15.538+01:00",
50
    publication_scheduled_at: null,
51
    unpublishing_scheduled_at: null,
52
    first_published_at: "2024-09-06T17:19:59.215+01:00",
53
    is_valid: true,
54
    is_current_version_valid: true,
55
    is_published_version_valid: true,
56
    status: "published",
57
    current_version: "EFYp72wJQf24L_jL1C1_tw",
58
    stage: null,
59
  },
60
}
61

62

63
/* Updated record. Only block IDs are returned, not their content.
64
{
65
  id: 'A4gkL_8pTZmcyJ-IlIEd2w',
66
  type: 'item',
67
  title: 'This is an example record with blocks in a modular content field',
68
  modular_content_field: [ 'ToBApjdYQaCgeFJxp_ty0A', 'YGrrPYrkSNaq-dBaP7aSaQ' ],
69
  item_type: { id: 'LvTZuGYRTQO9aBVk0g35Jw', type: 'item_type' },
70
  creator: { id: '627975', type: 'organization' },
71
  meta: {
72
    created_at: '2024-09-06T17:19:59.151+01:00',
73
    updated_at: '2024-10-03T00:41:21.730+01:00',
74
    published_at: '2024-10-03T00:41:21.784+01:00',
75
    publication_scheduled_at: null,
76
    unpublishing_scheduled_at: null,
77
    first_published_at: '2024-09-06T17:19:59.215+01:00',
78
    is_valid: true,
79
    is_current_version_valid: true,
80
    is_published_version_valid: true,
81
    status: 'published',
82
    current_version: 'Af6ykuN7S6WGMcwD3XZUdQ',
83
    stage: null
84
  }
85
}
86
*/

You can reorder block records by changing their IDs position in the modular content field array.

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const itemId = "4235";
8
  const item = await client.items.update(itemId, {
9
    // previous order was ['565346546', '565346547', '565346548']
10
    content: ["565346548", "565346547", "565346546"],
11
  });
12

13
  console.log(item);
14
}
15

16
run();

1
const result = {
2
  type: "item",
3
  id: "4235",
4
  title: "Title",
5
  content: ["565346548", "565346547", "565346546"],
6
  meta: {
7
    /* ... */
8
  },
9
  item_type: { type: "item_type", id: "44" },
10
  creator: { type: "access_token", id: "312" },
11
};

In this case, you must not pass an ID to buildBlockRecord.

It's not required the presence of all the fields in the payload. If it's easier for you to include all of them, just pass null, as it's a valid value for every field type.

When a field is not present in the payload, or its value is null, then the field's default value will be used (if available).

1
import { buildClient, buildBlockRecord } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const itemId = "4235";
8
  const item = await client.items.update(itemId, {
9
    // previous order was ['565346546', '565346547', '565346548']
10
    content: ["565346548", "565346547", "565346546"],
11
  });
12

13
  console.log(item);
14
}
15

16
run();
17

18
async function run() {
19
  // Make sure the API token has access to the CMA, and is stored securely
20
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
21

22
  const itemId = "4235";
23
  const blockModelId = "23455234";
24

25
  const item = await client.items.update(itemId, {
26
    content: [
27
      // new block record:
28
      buildBlockRecord({
29
        item_type: { type: "item_type", id: blockModelId },
30
        text: "new block record text",
31
        subtext: "another text",
32
      }),
33
      // existing block record IDs:
34
      "565346546",
35
      "565346547",
36
      "565346548",
37
    ],
38
  });
39

40
  console.log(item);
41
}
42

43
run();

1
const result = {
2
  type: "item",
3
  id: "4235",
4
  title: "Title",
5
  // block '565346549' has been added:
6
  content: ["565346549", "565346546", "565346547", "565346548"],
7
  meta: {
8
    /* ... */
9
  },
10
  item_type: { type: "item_type", id: "44" },
11
  creator: { type: "access_token", id: "312" },
12
};

To delete a block record, remove its ID from the modular content field array.

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const itemId = "4235";
8

9
  const item = await client.items.update(itemId, {
10
    // previous value was ['565346546', '565346547', '565346548'], let's remove '565346547'
11
    content: ["565346546", "565346548"],
12
  });
13

14
  console.log(item);
15
}
16

17
run();

1
const result = {
2
  type: "item",
3
  id: "4235",
4
  title: "Title",
5
  // block '565346547' has been removed!
6
  content: ["565346546", "565346548"],
7
  meta: {
8
    /* ... */
9
  },
10
  item_type: { type: "item_type", id: "44" },
11
  creator: { type: "access_token", id: "312" },
12
};

Working with localized content

Before diving in, the key concepts to remember are the following:

Localization is handled on a per-field basis. That is, in the same model, some fields can have a different value specified for each locale, and some others just a single (non-localized) value.
On localized fields, records express a value for multiple locales using an object, whose keys represent the environment’s locales.
The locales specified in a record must be coherent across each localized field. That is, if you have two localized fields, they must share the same locale keys. You cannot ie. specify locales en and it for the title field, and only en for the content field.
When a model contains one or more localized fields, it can enforce the presence of a value for all locales, or not.
Every user/API token is linked to a role, which in turn specifies which locales can be managed by the user/API token itself on a per-model level.

Above we said that when you perform an update operation to a record, you can pass just the fields you want to change, and not all of them. When dealing with localized content, the only exception to this rule is when you have a model that does not enforce a value for every locale, and you want to add or remove a locale on a specific record. Only in this case, you are required to pass all localized fields in the payload to enforce a locales coherence between all the localized fields.

Also, when you want to update the value for a specific localized field, you always need to pass an object containing the value for each locale you want to preserve, not just the one you might want to update, otherwise you’ll get an error.

If your API token can only manage a subset of locales, during an update operation you are required not to include in the payload any other locales. In this case, the content for the locales you cannot control and that you won’t pass will be kept intact by the system.

In the following table, you’ll find a recap showing the result of an update operation, depending on the API token permissions, the locales already present in a record, and the locales specified in the payload of the update operation itself:

Role can manage content in	Record contains localized fields with content in	Payload contains all localized fields with content in	Result for the update operation
English	English	English	English is updated.
English, Italian	English	English, Italian	English is updated. Italian is added.
English, Italian	English, Italian	English	English is updated. Italian is removed.
English, Italian	English, Italian	English, Italian	English is updated. Italian is updated.
English, Italian, French	English, Italian	English, French	English is updated. Italian is removed. French is added.
English	English, Italian	English	English is updated. Italian is preserved.
English, Italian	English, French	English, Italian	English is updated. French is preserved. Italian is added.
English, Italian	English, French	Italian	English is removed. French is preserved. Italian is added.

If the 'All locales required?' option in a model is turned off, then its records do not need all environment's locales to be defined for localized fields, so you're free to add/remove locales during an update operation.

Suppose your environment's locales are English, Italian and German (['en', 'it', 'de']) and the following record currently defines en and it locales on its localized fields (title and content):

1
const item = {
2
  id: '4235',
3
  // localized field
4
  title: {
5
    en: 'My title',
6
    it: 'Il mio titolo'
7
  },
8
  // localized field
9
  content: {
10
    en: 'Article content',
11
    it: 'Contenuto articolo',
12
  },
13
  // non-localized field
14
  votes_count: 10,
15
  meta: { /* ... */ },
16
  item_type: { type: 'item_type', id: '44' },
17
  creator: { type: 'access_token', id: '312' },
18
}

To add the de locale to this record, you have to send an update request containing all localized fields. For each one of these, you must define the exiting locales plus the ones you want to add:

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const itemId = "4235";
8

9
  const item = await client.items.update(itemId, {
10
    title: {
11
      en: "My title",
12
      it: "Il mio titolo",
13
      de: "Mein Titel",
14
    },
15
    content: {
16
      en: "Article content",
17
      it: "Contenuto articolo",
18
      de: "Artikelinhalt",
19
    },
20
  });
21

22
  console.log(item);
23
}
24

25
run();

1
const result = {
2
  type: "item",
3
  id: "4235",
4
  title: {
5
    en: "My title",
6
    it: "Il mio titolo",
7
    de: "Mein Titel",
8
  },
9
  content: {
10
    en: "Article content",
11
    it: "Contenuto dell'articolo",
12
    de: "Artikelinhalt",
13
  },
14
  votes_count: 10,
15
  meta: {
16
    /* ... */
17
  },
18
  item_type: { type: "item_type", id: "44" },
19
  creator: { type: "access_token", id: "312" },
20
};

Let's suppose your environment's locales are English (en), Italian (it) and German (de) and the following record currently defines en and it locales on its localized fields (title and content):

1
const item = {
2
  id: '4235',
3
  // localized field
4
  title: {
5
    en: 'My title',
6
    it: 'Il mio titolo'
7
  },
8
  // localized field
9
  content: {
10
    en: 'Article content',
11
    it: 'Contenuto articolo',
12
  },
13
  // non-localized field
14
  votes_count: 10,
15
  meta: { /* ... */ },
16
  item_type: { type: 'item_type', id: '44' },
17
  creator: { type: 'access_token', id: '312' },
18
}

To remove the it locale from this record, you have to send an update request containing all localized fields. For each one fo these, you must define the exiting locales, except the ones you want to remove:

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const itemId = "4235";
8
  const item = await client.items.update(itemId, {
9
    title: {
10
      en: "My title",
11
    },
12
    content: {
13
      en: "Article content",
14
    },
15
  });
16

17
  console.log(item);
18
}
19

20
run();

1
const result = {
2
  type: "item",
3
  id: "4235",
4
  title: {
5
    en: "My title",
6
  },
7
  content: {
8
    en: "Article content",
9
  },
10
  votes_count: 10,
11
  meta: {
12
    /* ... */
13
  },
14
  item_type: { type: "item_type", id: "44" },
15
  creator: { type: "access_token", id: "312" },
16
};

Body parameters

meta.created_at string Optional

Date of creation

meta.first_published_at null, string Optional

Date of first publication

meta.current_version string Optional

The ID of the current record version (for optimistic locking, see the example)

Example:

"4234"

meta.stage string, null Optional

The new stage to move the record to

item_type Optional

The record's model

Type: ResourceLinkage<"item_type">

creator Optional

The entity (account/collaborator/access token/sso user) who created the record

Type: ResourceLinkage<"account">, ResourceLinkage<"access_token">, ResourceLinkage<"user">, ResourceLinkage<"sso_user">, ResourceLinkage<"organization">

Returns

Returns a resource object of type item

Did this doc help you?

Need help?

Explore our forum, contact support, or connect with our sales team . You can also chat live with other users in our Slack channel.