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
PUTmethod instead ofPOST. - 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=='
