Container API

Last Updated: Aug 4, 2022
documentation for the dotCMS Content Management System

dotCMS templates are built out of containers, which define display behaviors for different Content Types in the context of different page layouts. This document details the endpoints of a REST API for manipulating containers with create, read, update, and delete (CRUD) operations, utilizing and returning JSON objects.

Containers can exist either as database entities or as file system entities — directories containing VTL files. The latter case offers advantages such as easy storage on remote repositories, synchronization through WebDav or command-line interface, or other similar conveniences. By the same measure, there are also some Container API calls that can only be performed on the database-entity type of Container.

All examples use the dotCMS demo site as their target. Used on another host, the Authentication header must change accordingly: For Basic authorization, use base64 encoding of a username:password string; for more secure Bearer authorization, use an API token.

Retrieving a Container

The endpoint offers several methods to retrieve containers, individually or collectively. Please note:

  • Containers located in the database must be requested by identifier.
  • Containers located in the file system must be referenced by path.

To retrieve the working version of a container, use /working:

curl --location --request GET 'https://demo.dotcms.com/api/v1/containers/working?containerId=REPLACE_THIS_UUID' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg=='

To retrieve the live version of a container, call /live:

curl --location --request GET 'https://demo.dotcms.com/api/v1/containers/live?containerId=/application/containers/system' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg==' \

Finally, to retrieve all containers:

curl --location --request GET 'https://demo.dotcms.com/api/v1/containers/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg=='

To adjust the displayed results, the Container API uses standard pagination parameters such as per_page, filter, etc.

A successful call returns containers as JSON objects, which may look, in part, like the following data:

{
    "entity": {
        "archived": false,
        "categoryId": "27d80ebe-c9f1-4dd9-8cae-f15e644df708",
        "deleted": false,
        "friendlyName": "TestContainer description",
        "iDate": 1647630014297,
        "idate": 1647630014297,
        "identifier": "567416cee048a876d4c60172421832ba",
        "inode": "27d80ebe-c9f1-4dd9-8cae-f15e644df708",
        "live": false,
        "locked": false,
        "map": {
            "deleted": false,
            "friendlyName": "TestContainer description",
            "hasLiveVersion": false,
            "iDate": 1647630014297,
            "identifier": "567416cee048a876d4c60172421832ba",
            "inode": "27d80ebe-c9f1-4dd9-8cae-f15e644df708",
            "live": false,
            "locked": false,
            "modDate": 1647630014309,
            "modUser": "dotcms.org.1",
            "modUserName": "Admin User",
            "showOnMenu": false,
            "sortOrder": 0,
            "title": "TestContainer",
            "type": "containers",
            "working": true
        }
       ...
    }
}

Adding a Container

Adding a container by API call is only possible with a database-style container. A container that exists in the file system must instead be created by adding a folder containing the necessary VTL files within the application/containers folder, either manually or by one of the methods detailed at the top of the page.

To add a container, make a POST call with the Container as a JSON payload:

curl --location --request POST 'https://demo.dotcms.com/api/v1/containers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg==' \
--data-raw '{
   "title":"TestContainer",
   "friendlyName":"TestContainer description",
   "maxContentlets":1,
   "notes":"Notes",
   "preLoop":"<h1>Some Title</h1>",
   "postLoop":"<span>Some Footer</span>",
   "containerStructures":[
        {
            "structureId":"webPageContent",
            "code":"<div> $!{body} </div>"
        },
        {
            "structureId":"DotAsset",
            "code":" <img src ='\''./contentAsset/image/${ContentIdentifier}/asset'\'' />"
        }
    ]
}'

Updating a Container

The call to update a container is similar to creating one; it only functioning with database containers, and it has a very similar structure. However, there are two key differences:

  • It uses the PUT method instead of POST.
  • It includes the container's identifier in the payload data.
curl --location --request PUT 'https://demo.dotcms.com/api/v1/containers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg==' \
--data-raw '{
    "identifier":"567416cee048a876d4c60172421832ba",
    "title":"TestContainer",
    "friendlyName":"TestContainer description",
    "maxContentlets":1,
    "notes":"Notes 1",
    "preLoop":"preLoop xxxx",
    "postLoop":"postLoop xxxx",
    "containerStructures":[
        {
            "structureId":"webPageContent",
            "code":" code xxxx"
        },
        {
            "structureId":"DotAsset",
            "code":" tags: $!{tags}"
        }
    ]
}'

Publishing or Unpublishing a Container

Publishing or unpublishing a container are similar PUT operations, distinguished by the use of /_publish or /_unpublish. Both operations take either a path or an identifier.

Publishing:

curl --location --request PUT 'https://demo.dotcms.com/api/v1/containers/_publish?containerId=567416cee048a876d4c60172421832ba' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg=='

Unpublishing:

curl --location --request PUT 'https://demo.dotcms.com/api/v1/containers/_unpublish?containerId=567416cee048a876d4c60172421832ba' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg=='

Archiving or Unarchiving a Container

Archiving and unarchiving works similarly to publishing or unpublishing. Note: Before archiving, containers should be unpublished.

To archive:

curl --location --request PUT 'https://demo.dotcms.com/api/v1/containers/_archive?containerId=/application/containers/system' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg=='

To unarchive an archived container:

curl --location --request PUT 'https://demo.dotcms.com/api/v1/containers/_unarchive?containerId=/application/containers/system' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg=='

Deleting a Container

Finally, you can use the call below to delete a container. Note: A container should be archived (see above) before deletion.

curl --location --request DELETE 'https://demo.dotcms.com/api/v1/containers?containerId=567416cee048a876d4c60172421832ba' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW5AZG90Y21zLmNvbTphZG1pbg=='

On this page