Update a record - Record - Content Management API

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.

Parameters

meta.createdAt string Optional

Date of creation

meta.firstPublishedAt null, string Optional

Date of first publication

meta.unpublishingScheduledAt null, string Optional

Date of future unpublishing

meta.currentVersion string Optional

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

relationships.creator { type: "account", id: account.id }, { type: "access_token", id: access_token.id }, { type: "user", id: user.id }, { type: "sso_user", id: sso_user.id } Optional

Returns

Returns a item object.

Simple update operation

Example code:

const SiteClient = require("datocms-client").SiteClient;
const client = new SiteClient("YOUR-API-TOKEN");
const itemId = "4235";
client.items
  .update(itemId, {
    title: "[EDIT] My first blog post!",
  })
  .then((item) => {
    console.log(item);
  })
  .catch((error) => {
    console.error(error);
  });

Returned output:

> node example.js
{
  "id": "4235",
  "title": "[EDIT] My first blog post!",
  "content": "Lorem ipsum dolor sit amet...",
  "category": "24",
  "image": {
    "uploadId": "1235",
    "alt": "Alt text",
    "title": "Image title",
    "customData": {}
  },
  "meta": {
    "created_at": "2020-04-21T07:57:11.124Z",
    "updated_at": "2020-04-21T07:57:11.124Z",
    "published_at": "2020-04-21T07:57:11.124Z",
    "first_published_at": "2020-04-21T07:57:11.124Z",
    "publication_scheduled_at": "2020-04-21T07:57:11.124Z",
    "unpublishing_scheduled_at": "2020-04-22T07:57:11.124Z",
    "status": "draft",
    "is_valid": true,
    "current_version": "4234"
  },
  "itemType": "44",
  "creator": "312"
}

Optimistic-locking update operation

Example code:

import { SiteClient, ApiException } from "datocms-client";
const client = new SiteClient("YOUR-API-TOKEN");
async function incrementCounter() {
  const itemId = "4235";
  // first we get the record we want to update
  const record = await client.items.find(itemId);
  try {
    // now we increment a field's value, passing the current version
    // to enable optimistic-locking
    client.items.update(itemId, {
      counter: record.counter + 1,
      meta: { currentVersion: record.meta.currentVersion },
    });
    console.log("Done!");
  } catch (e) {
    // if we get a STALE_ITEM_VERSION error, this means that the
    // the record changed in-between the find and update operations, so we have
    // to fetch the latest version of the record and try again
    if (e instanceof ApiException && e.errorWithCode("STALE_ITEM_VERSION")) {
      console.log("Stale version, retrying...");
      return incrementCounter();
    }
    throw e;
  }
}
incrementCounter();

Returned output:

> node example.js
Stale version, retrying...
Stale version, retrying...
Done!

Questions?

We're always happy to help with code or other questions you might have. Search our documentation, forum, contact support, or connect with our sales team. You can chat live with other developers in our Slack channel.