DatoCMS Content Management API Client (Deprecated)

Common errors

• #/data: failed schema #/definitions/item/links/13/schema/properties/data: "id" is not a permitted key.

  cause This error occurs when attempting to use `item.publish()` with the deprecated `datocms-client` and passing an empty object as the request body, which triggers an old serialization bug.
  fix With the deprecated client, pass `{ serializeRequest: false }` as the fourth argument to `client.items.publish(itemId, {}, {}, { serializeRequest: false })`. For a long-term solution, migrate to `@datocms/cma-client-node` and use `client.items.publish(itemId)` without any body.

• Error: ENODEV: no such device or address, unlink './image.png'

  cause The deprecated `datocms-client` may have inconsistent or limited support for file system operations in various environments, particularly when handling local file uploads.
  fix The new `@datocms/cma-client-node` offers specialized helper methods like `createFromLocalFile()` and `createFromUrl()` that are robustly designed for Node.js file system access. For browser environments, `@datocms/cma-client-browser` provides `createFromFileOrBlob()`. Use the appropriate modern client for reliable file uploads.

Warnings

• breaking The `datocms-client` package is officially deprecated and is no longer maintained. It will not receive new features, bug fixes, or security updates. Developers should migrate to `@datocms/cma-client-node` or `@datocms/cma-client-browser` immediately.
  Fix: Migrate your codebase to use the new DatoCMS JavaScript CMA clients: `@datocms/cma-client-node` for Node.js or `@datocms/cma-client-browser` for browsers. Install the new package and refactor your API calls according to the updated documentation.
• breaking Direct creation, duplication, updating, or deletion of modular block items using legacy endpoints (`POST /items`, `PUT /items/:id`, etc.) was deprecated as of February 1st, 2020. Operations on modular block items must now be done by updating the modular content field on the parent item.
  Fix: Ensure all modular block operations are performed by modifying the parent item's modular content field. This change affects how `datocms-client` users interact with modular content programmatically.
• gotcha When using `item.publish()` with the deprecated `datocms-client`, a known issue exists where passing an empty body (`{}`) can result in an error: "`id` is not a permitted key". The deprecated client's internal serialization rules may cause this.
  Fix: As a temporary workaround for the deprecated client, you can pass `{ serializeRequest: false }` as an option to `item.publish()`. However, the permanent fix is to upgrade to `@datocms/cma-client-node` where this issue is resolved and `item.publish()` without a body publishes the entire record.
• deprecated The `exists` filter for string, text, and Structured Text fields in the DatoCMS Content Delivery API (CDA) is deprecated. It previously returned empty strings instead of `null` values, leading to confusing behavior.
  Fix: Use the new `isPresent` filter, which selects values that are neither `null` nor empty strings, or `isBlank` for its opposite. While the `exists` filter still works for now, it will be removed in future API versions.

Install

• npm install datocms-client npm
• yarn add datocms-client yarn
• pnpm add datocms-client pnpm

Imports

• SiteClient
  wrong:

  const SiteClient = require('datocms-client').SiteClient;

  correct:

  import { SiteClient } from 'datocms-client';

  This is the primary class for interacting with the DatoCMS Content Management API using the *deprecated* client. Prefer named imports even for deprecated packages.
• buildModularBlock

  import { buildModularBlock } from 'datocms-client';

  Used for constructing modular block data when creating or updating items with the *deprecated* client. Ensure you are handling modular blocks correctly as API behavior for them has changed.

Quickstart

Demonstrates basic initialization and fetching item types using the deprecated `datocms-client`. Includes a strong warning about its deprecation and outlines the recommended migration path.

import { SiteClient } from 'datocms-client';

// ⚠️ WARNING: This package is DEPRECATED. Please migrate to @datocms/cma-client-node.
// See: https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients

const API_TOKEN = process.env.DATOCMS_API_TOKEN ?? '';

if (!API_TOKEN) {
  console.error('DATOCMS_API_TOKEN environment variable is not set.');
  process.exit(1);
}

async function createItemWithDeprecatedClient() {
  try {
    const client = new SiteClient(API_TOKEN, { 
      // 'logApiCalls' is an option available in the deprecated client
      // It logs API requests and responses.
      logApiCalls: true
    });

    console.log('--- Using deprecated datocms-client ---');
    // Example: Fetch existing item types
    const itemTypes = await client.itemTypes.all();
    console.log(`Found ${itemTypes.length} item types. Example: ${itemTypes[0]?.api_key}`);

    // Example: Create a new item (simplified, usually requires more fields)
    // This operation might be subject to the 'id' not permitted key issue.
    // const newItem = await client.items.create({
    //   itemType: itemTypes[0].id, // Use an existing item type ID
    //   title: `My Deprecated Item ${Date.now()}`,
    //   // ... other fields
    // });
    // console.log('Created item:', newItem.id);

  } catch (error) {
    console.error('Error using deprecated datocms-client:', error);
    if (error.findError) {
      console.error('API Error details:', error.findError('INVALID_FIELD'));
    }
  }
}

createItemWithDeprecatedClient();

/*
// Recommended alternative using @datocms/cma-client-node (install separately):
// npm install @datocms/cma-client-node

// import { buildClient } from '@datocms/cma-client-node';

// async function createItemWithNewClient() {
//   try {
//     const client = buildClient({ apiToken: API_TOKEN });
//     console.log('\n--- Using recommended @datocms/cma-client-node ---');
//     const itemTypes = await client.itemTypes.list(); // Note: method names might differ (all vs list)
//     console.log(`Found ${itemTypes.length} item types. Example: ${itemTypes[0]?.api_key}`);

//     // Example: Create a new item (requires a valid item type ID from your DatoCMS project)
//     // const modelId = itemTypes.find(mt => mt.api_key === 'article')?.id; // Find an existing model
//     // if (modelId) {
//     //   const newItem = await client.items.create({
//     //     item_type: { type: 'item_type', id: modelId },
//     //     attributes: { title: `My New Item ${Date.now()}` }
//     //   });
//     //   console.log('Created item with new client:', newItem.id);
//     // }

//   } catch (error) {
//     console.error('Error using new DatoCMS client:', error);
//   }
// }

// createItemWithNewClient();
*/