contensis-delivery-api

contensis-delivery-api

Create a Contensis client that allows you to query and retrieve entries, site view nodes, content types and projects. 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-delivery-api-examples repository containing Express.js, React and Angular test applications, as well as an extended example using nodes api in a Node.js project.

Use with Contensis version 12.0 and above. For Contensis 11.3 support use this version | npm. 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-delivery-api

Usage

Follow the examples with the preferred coding style that best suits your project

Create a client

All of the delivery methods are available under the client instance returned by Client.create(...)

Use the provided intellisense to guide you where it is available

// Using TypeScript, or ES Module syntax

import { Client } from "contensis-delivery-api";

const client = Client.create({
  rootUrl: "https://my-cms.com",
  accessToken: "DELIVERY_API_ACCESS_TOKEN",
  projectId: "website",
  language: "en-GB",
  versionStatus: "published",
});

// Using Common JS syntax

const Client = require("contensis-delivery-api").Client;

const client = Client.create({
  rootUrl: "https://my-cms.com",
  accessToken: "DELIVERY_API_ACCESS_TOKEN",
  projectId: "website",
  language: "en-GB",
  versionStatus: "published",
});

Get a list of entries

Reusing the client instance we created above

// Using TypeScript, or ES Module syntax

const loadMovies = async () => {
  const movieList = await client.entries.list({
    contentTypeId: "movie",
    pageOptions: { pageIndex: 0, pageSize: 10 },
    order: ["-releaseDate"],
  });
  for (const movie of movieList.items) {
    console.log(movie);
  }
};

loadMovies();

Create a client config and get a list of entries

Keep a common client configuration and create the delivery client when you need it

// Using async / await syntax (avoiding callbacks)

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

// Remove ": Config" annotation when NOT using TypeScript
const contensisConfig: Config = {
  rootUrl: "https://my-cms.com",
  accessToken: "DELIVERY_API_ACCESS_TOKEN",
  projectId: "website",
  language: "en-GB",
  versionStatus: "published",
};

const loadMovies = async () => {
  const client = Client.create(contensisConfig);
  const movieList = await client.entries.list({
    contentTypeId: "movie",
    pageOptions: { pageIndex: 0, pageSize: 10 },
    order: ["-releaseDate"],
  });
  for (const movie of movieList.items) {
    console.log(movie);
  }
};

loadMovies();

// Using Promises and callbacks

import { Client } from "contensis-delivery-api";

const contensisConfig = {
  rootUrl: "https://my-cms.com",
  accessToken: "DELIVERY_API_ACCESS_TOKEN",
  projectId: "website",
  language: "en-GB",
  versionStatus: "published",
};

function loadMovies() {
  const client = Client.create(contensisConfig);
  client.entries
    .list({
      contentTypeId: "movie",
      pageOptions: { pageIndex: 0, pageSize: 10 },
      order: ["-releaseDate"],
    })
    .then((movieList) => {
      console.log(movieList.items);
    });
}

loadMovies();

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.

The build of the library that targets browsers can be found in the bundle folder.

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-delivery-api";
import enterpriseFetch from "enterprise-fetch";

const client = Client.create({
  rootUrl: "https://my-cms.com",
  accessToken: "DELIVERY_API_ACCESS_TOKEN",
  projectId: "website",
  language: "en-GB",
  versionStatus: "published",
  fetchFn: enterpriseFetch,
});

Changelog

[1.5.0] - 2024-10-10

Added

• added additional Entry types

Changed

• refactor various Entry types based on PS usage
• updated project README