Go to main content

Create content item with Kentico Cloud Content Management API

In this post I will briefly explain logic behind creating content items with the Kentico Cloud Content Management API and provide you with a Node.js code example. 

Create content item with Kentico Cloud Content Management API

Kentico launched beta version of their new Content Management API. Amazing about this API is that it brings possibility of writing data! Now you can create, update and delete content items in your code. Here you can read documentation.

The API works in a very similar manner to the Delivery API. However, there are several differences you need to keep in mind: 

  • It uses other domain for endpoints: https://manage.kenticocloud.com/.
  • All requests have to be authenticated with the Content Management API key.
  • The Content Management API key is valid for 30 days after you generate it.
  • The primary use-case seems to be for one-off content migration. Not for writing data from your application UI. 
  • Listing  returns only general data about content items so doesn't replace the Delivery API.
  • To create and fill content item with data you need to make 2 or more requests:
    • The first one creates the content item and fills with general data.
    • The other ones fill content elements with data. Each language variant of the content item requires one additional request.

To give you an idea of how the API could used I created the following code example in Node.js. It creates a new content item and fills its content elements with data in one language variant.

The code example has 2 dependencies:

npm install --save request
npm install --save request-promise
const requestPromise = require('request-promise');

// Information needed for the content item creation 
var settings = {
    projectId: '548121...4ab0950', // Project ID, see details in the Kentico Cloud Developers Hub: https://developer.kenticocloud.com/docs/using-delivery-api#section-getting-project-id
    contentManagementAPIKey: 'ew0Ks4LvlH...30Fp23ieA8',  // Content Management API Key, see details in the Kentico Cloud Developers Hub: https://developer.kenticocloud.com/reference#content-management-api
    languageVariantCodename: 'default', // Codename of the content language, see details: https://developer.kenticocloud.com/reference#content-management-api-view-variant-by-item-codename-language-id 
    // Complete data for item creation
    // name, type and sitemap_locations properties are needed for adding item: https://developer.kenticocloud.com/reference#content-management-api-add-item
    // elements property is needed for filling content elements with content: https://developer.kenticocloud.com/reference#content-management-api-upsert-variant-by-item-id-language-codename 
    data: {
        name: 'Management API test post',
        type: {
            codename: 'blog_post'
        },
        sitemap_locations: [{
            codename: 'posts'
        }],
        elements: {
            heading: 'Management API test post'
        }
    }
}

// Helper function that returns object with specified keys
const getSpecificObjectKeys = (object, keys) => {
    var keysObject = {};

    keys.forEach((element) => {
        if (object[element]) {
            keysObject[element] = object[element];
        }  
    });

    return keysObject;
}

// Function that creates the content item in 2 step
// Step 1. - Adds content item to the Kentico Cloud Storage, https://developer.kenticocloud.com/reference#content-management-api-add-item
// Step 2. - Fills content elements of the content item with data, https://developer.kenticocloud.com/reference#content-management-api-upsert-variant-by-item-id-language-codename 
const createItem = (settings) => {

    // Split data into 2 separate objects for each step  
    var addData = getSpecificObjectKeys(settings.data, ['name', 'type', 'sitemap_locations']),
        upsertData = getSpecificObjectKeys(settings.data, ['elements']);

    // Request options for step 1
    var addOptions = {
        method: 'POST',
        uri: 'https://manage.kenticocloud.com/projects/' + settings.projectId + '/items',
        auth: {
            'bearer': settings.contentManagementAPIKey
        },
        body: addData,
        json: true
    };

    // Perform step 1 
    requestPromise(addOptions)
        .then((response) => {

            // Request options for step 2
            var upsertOptions = {
                method: 'PUT',
                uri: 'https://manage.kenticocloud.com/projects/' + settings.projectId + '/items/' + response.id + '/variants/codename/' + settings.languageVariantCodename,
                auth: {
                    'bearer': settings.contentManagementAPIKey
                },
                body: upsertData,
                json: true
            };

            // Perform step 2
            requestPromise(upsertOptions)
                .then((response) => {
                    console.log(response);
                })
                .catch((error) => {
                    console.error(error);
                });
        })
        .catch((error) => {
            console.error(error);
        });  
}

// Usage
createItem(settings);

This example could be extended to be able to create:

  • multiple content items
  • in multiple languages

to cover more advanced scenarios. Maybe topic for another post.

Milan Lund

is a freelance web developer and a proud Basenji owner. His specialties are Kentico CMS/EMS and Kentico Cloud.

Further reading

all posts