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 date-time Optional

Date of creation

meta.updatedAt date-time Optional

Last update time

meta.publishedAt null, date-time Optional

Date of last publication

meta.firstPublishedAt null, date-time Optional

Date of first publication

meta.publicationScheduledAt null, date-time Optional

Date of future publication

meta.status null, enum Optional

Status

meta.isValid boolean Optional

Whether the current record is valid or not

meta.currentVersion string Optional

The ID of the current record version

creator account.id, access_token.id, user.id, sso_user.id Optional

Returns

Returns a item object.

Examples

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",
    "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.