contensis-management-api

contensis-management-api

Create a Contensis client that allows you to manage various aspects of your Contensis environment, content or deployments. It can be used in all your JavaScript / TypeScript projects, whether it runs in a browser, Node.js app, or both.

Explore the docs on contensis.com and the contensis-management-api-examples repository containing Express.js and React examples.

Use with Contensis version 14.0 and above. This library requires Node.js 14 or above.

Installation

Install the package to your project dependencies using npm, or your preferred Node.js package manager.

npm install --save contensis-management-api

Note

Before following the rest of the examples we assume you have an existing Node.js / Express.js application that is already created.

To get started with a new Node.js app, inside a terminal, cd to your chosen directory and run npm init

Import the correct client

Depending on how and where your code is used you may need to find the right Client flavour to import that creates the Management Client best suited to your use case

Browser app

The default Client import targets primarily a modern browser and assumes the fetch API is already available.

// Using TypeScript, or ES Module syntax
import { Client } from "contensis-management-api";

// Using Common JS syntax
const Client = require("contensis-management-api").Client;

Universal JS app

Universal JavaScript describes a JavaScript application which runs both on the client and the server.

If your API interactions will be made using a part of your application that runs Universal or Isomorphic JavaScript you should instead use the UniversalClient

// Using TypeScript, or ES Module syntax
import { UniversalClient } from "contensis-management-api";

// Using Common JS syntax
const UniversalClient = require("contensis-management-api").UniversalClient;

Node.js app

For applications that run exclusively on a server, or via a terminal script you will likely want to import and use the NodejsClient

Some Management API functionality is only available in a Node.js environment for example creating and updating assets. The NodejsClient class ensures fetch API is made available and allows us to perform file operations with the fs API.

// Using TypeScript, or ES Module syntax
import { NodejsClient } from "contensis-management-api/lib/client";

// Using Common JS syntax
const NodejsClient =
  require("contensis-management-api/lib/client").NodejsClient;

Configure and create a client

The config argument passed to the Client.create(...) method represents the shared configuration that will be used by all Management API calls

Use the provided intellisense to guide you where it is available

// Import the additional "Config" type when using TypeScript
import { Client, Config } from "contensis-management-api";

// Remove ": Config" annotation when NOT using TypeScript
const config: Config = {
  rootUrl: "https://cms-example.cloud.contensis.com",
  projectId: "website",
  clientType: "client_credentials",
  clientDetails: {
    clientId: "6f8cf1e8-b2ee-49ad-9b94-2dbb09871903",
    clientSecret:
      "6d80c9a356ce4317bd71d92c5734d67a-4a837b1336344f63b1b24ce2dfa73945-ef09daa8d0f74b1e8e223779c392a67b",
  },
};

// Using the default Client
const client = Client.create(config);

// Using the UniversalClient
const client = UniversalClient.create(config);

// Using the NodejsClient
const client = NodejsClient.create(config);

Using the client

All of the API operations are available under the client instance returned by Client.create({ ...options })

// Using async / await syntax
const listContentTypes = async () => {
  try {
    const result = await client.contentTypes.list();

    console.log("API call result: ", result);
    return result;
  } catch (error) {
    console.log("API call fetch error: ", error);
    throw error;
  }
};

listContentTypes();

// Using Promises and callbacks
function listContentTypes() {
  client.contentTypes
    .list()
    .then((result) => {
      console.log("API call result: ", result);
      return result;
    })
    .catch((error) => {
      console.log("API call fetch error: ", error);
      throw error;
    });
}

listContentTypes();

For more examples refer to our documentation on contensis.com

Fetch API

This library uses the fetch API and relies on it being available at runtime.

Browser support

In modern browsers fetch is available natively, a polyfill is provided for older browsers.

Node.js support

When using this library in Node.js the fetch API is already polyfilled with cross-fetch package (which uses node-fetch when used with a Node.js runtime).

Node.js version 16 introduced experimental support for a native global fetch API and shipped as standard with Node.js versions 18 and 20. The global fetch support in Node.js version 21 and greater is marked as stable.

Use your own fetch

You can override the built-in fetch API by providing your own fetchFn method when creating the Client.

Method calls that require fetch invoked from this client instance will be made using your chosen API.

import { Client } from "contensis-management-api";
import enterpriseFetch from "enterprise-fetch";

const client = Client.create({
  ...config
  fetchFn: enterpriseFetch,
});

Changelog

[2.2.0] - 2024-10-10

Added

• users: supports search in user operations
• users: supports setPasswordToExpirable action in user operations
• groups: add child groups to a group in bulk with addChildGroups in group operations
• groups: added includeSelf option when getting child groups of a group

Changed

• updated project README