Management API

Contents

Management API

Management commands are available at port 4848, i.e. localhost:4848 if you’re running XP locally

Snapshots

Commands for manipulating repository snapshots

Create

Create a snapshot of all or a single repository while running. The snapshots will be stored in the directory given in snapshots.dir option in the Repo Configuration (default $xp_home/snapshots). Note that the first snapshot only stores markers in the repository for the current state. Subsequent snapshots stores the changes since the last snapshot. See Backup and Restore for more information on snapshots.

For a clustered installation, the snapshot-location must be on a shared file-system.
Url
POST repo/snapshot
Table 1. Params
Param Type Description

repositoryId

String

the name of the repository to snapshot.

Response
{
    "Name": "2019-06-13t13-10-51.973z",
    "Reason": "",
    "State": "SUCCESS",
    "Timestamp": "2019-06-13T13:10:52.575Z",
    "Indices": [
        "search-com.enonic.cms.default",
        "storage-com.enonic.cms.default",
        "search-system-repo",
        "storage-system-repo"
    ]
}

List

List all the snapshots for the installation. See Backup and Restore for more information on snapshots.

Url
GET repo/snapshot/list
Response
{
    "Results": [
        {
            "Name": "2019-06-13t13-10-51.973z",
            "Reason": "",
            "State": "SUCCESS",
            "Timestamp": "2019-06-13T13:10:52.575Z",
            "Indices": [
                "search-com.enonic.cms.default",
                "storage-com.enonic.cms.default",
                "search-system-repo",
                "storage-system-repo"
            ]
        },
        {
            "Name": "2019-06-13t13-36-35.407z",
            "Reason": "",
            "State": "SUCCESS",
            "Timestamp": "2019-06-13T13:36:35.488Z",
            "Indices": [
                "search-com.enonic.cms.default",
                "storage-com.enonic.cms.default",
                "search-system-repo",
                "storage-system-repo"
            ]
        }
    ]
}

Restore

Restore a named snapshot. See Backup and Restore for more information on snapshots.

Url
POST repo/snapshot/restore
Table 2. Params
Param Type Description

snapshotName

String

snapshot name to restore

repository

String

the name of the repository to restore

Response
{
    "Message": "Restore successfull, 4 shards restored",
    "Name": "2019-06-13t13-10-51.973z",
    "Failed": false,
    "Indices": [
        "search-com.enonic.cms.default",
        "storage-com.enonic.cms.default",
        "search-system-repo",
        "storage-system-repo"
    ]
}

Delete

Deletes a snapshot by name or date:

Url
POST repo/snapshot/delete
Table 3. Params
Param Type Description

before

Date

date to delete snapshots up to

snapshotNames

String[]

List of snapshot names to delete

Response
{
    "DeletedSnapshots": [
        "2019-06-13t13-36-35.407z"
    ]
}

Dumps

List of command for manipulating all repositories

Create

Export data from every repository. The result will be stored in the $XP_HOME/data/dump directory.

Url
POST system/dump
Table 4. Params
Param Type Description

name

String

dump name

includeVersions

Boolean

dump version-history along with current versions

maxAge

Number

max age of versions to include, in days, in addition to current version

maxVersions

Number

max number of versions to dump in addition to current version

Response
{
    "Repositories": [
        {
            "RepositoryId": "com.enonic.cms.default",
            "Versions": 0,
            "Branches": [
                {
                    "Branch": "master",
                    "Successful": 3,
                    "Errors": []
                },
                {
                    "Branch": "draft",
                    "Successful": 3,
                    "Errors": []
                }
            ]
        },
        {
            "RepositoryId": "system-repo",
            "Versions": 0,
            "Branches": [
                {
                    "Branch": "master",
                    "Successful": 22,
                    "Errors": []
                }
            ]
        }
    ]
}

Upgrade

Upgrade a data dump from a previous version to the current version. The output of the upgrade will be placed alongside the dump that is being upgraded and will have the name <dump-name>_upgraded_<new-version>.

The current version XP installation must be running with the upgraded app deployed.
Url
POST system/upgrade
Table 5. Params
Param Type Description

name

String

dump name

Response
{
    "InitialVersion": "8.0.0",
    "UpgradedVersion": "8.0.0"
}

Load

Load data from a named system dump into Enonic XP. The dump read has to be stored in the $XP_HOME/data/dump directory. See Export and Import for more information on system dump/load.

A load will delete all existing repositories before loading the repositories present in the system-dump
Url
POST system/load
Table 6. Params
Param Type Description

name

String

dump name to load

upgrade

Boolean

upgrade the dump if necessary (default is false)

Response
{
    "Repositories": [
        {
            "Repository": "system-repo",
            "Versions": {
                "Errors": [],
                "Successful": 0
            },
            "Branches": [
                {
                    "Branch": "master",
                    "Successful": 22,
                    "Errors": []
                }
            ]
        },
        {
            "Repository": "com.enonic.cms.default",
            "Versions": {
                "Errors": [],
                "Successful": 0
            },
            "Branches": [
                {
                    "Branch": "draft",
                    "Successful": 3,
                    "Errors": []
                },
                {
                    "Branch": "master",
                    "Successful": 3,
                    "Errors": []
                }
            ]
        }
    ]
}

Export

Export and import data from a given repository, branch and content path.

Create

Extract data from a given repository, branch and content path. The result will be stored in the $XP_HOME/data/export directory. This is useful to move a part of a site from one installation to another. See Export and Import for more information on content export/import.

Exporting content will not include the version history of the content, just the current version.
Url
POST repo/export
Table 7. Params
Param Type Description

exportName

String

target name to save export

sourceRepoPath

String

path of data to export. Format: <repo-name>:<branch-name>:<node-path> e.g. cms-repo:draft:/some-content

exportWithIds

Boolean

Flag to include or skip ids in data when exporting.

includeVersions

Boolean

Flag to include or skip versions in data when exporting.

dryRun

Boolean

Show the result without making actual changes.

Response
{
    "DryRun": false,
    "ExportedBinaries": [],
    "ExportedNodes": [
        "/",
        "/content",
        "/issues"
    ],
    "Errors": null
}

Import

Import data from a named export into Enonic XP at the desired content path. The export read has to be stored in the $XP_HOME/data/export directory. See Export and Import for more information on content export/import.

Url
POST repo/import
Table 8. Params
Param Type Description

exportName

String

a named export to import

targetRepoPath

String

target path for import. Format: <repo-name>:<branch-name>:<node-path> e.g. cms-repo:draft:/some-content

xslSource

String

path to xsl file (relative to <XP_HOME>/data/export) for applying transformations to node.xml before importing

xslParams

JSON

parameters to pass to the XSL transformations before importing nodes. Format: {"applicationId": "com.enonic.myapp"}

importWithIds

Boolean

flag to include or skip ids when importing

importWithPermissions

Boolean

flag to include or skip permissions when importing

dry

Boolean

show the result without making actual changes.

Response
{
    "AddedNodes": [],
    "UpdateNodes": [
        "/",
        "/content",
        "/issues"
    ],
    "ImportedBinaries": [],
    "ImportErrors": [],
    "DryRun": false
}

An XSL file and a set of name=value parameters can be optionally passed for applying transformations to each node.xml file, before importing it.

This option could for example be used for renaming types or fields. The .xsl file must be located in the $XP_HOME/data/export directory.

Applications

Commands to install applications to the running enonic XP instance.

Install from file

Installs an application from file on all nodes.

Url
POST app/install
Table 9. Params
Param Type Description

file

File

File of the application

Response
{
    "ApplicationInstalledJson": {
        "Application": {
            "DisplayName": "Content Studio",
            "Key": "com.enonic.app.contentstudio",
            "Deletable": false,
            "Editable": false,
            "Local": false,
            "MaxSystemVersion": "8.0.0",
            "MinSystemVersion": "7.0.0",
            "ModifiedTime": "2019-06-13T14:48:30.314Z",
            "State": "started",
            "Url": "",
            "VendorName": "Enonic AS",
            "VendorUrl": "http://enonic.com",
            "Version": "1.0.0.SNAPSHOT"
        }
    },
    "Failure": ""
}

Install from URL

Installs an application from url on all nodes.

Url
POST app/installUrl
Table 10. Params
Param Type Description

URL

String

application URL

Response
{
    "ApplicationInstalledJson": {
        "Application": {
            "DisplayName": "Content Studio",
            "Key": "com.enonic.app.contentstudio",
            "Deletable": false,
            "Editable": false,
            "Local": false,
            "MaxSystemVersion": "8.0.0",
            "MinSystemVersion": "7.0.0",
            "ModifiedTime": "2019-06-13T14:50:53.917Z",
            "State": "started",
            "Url": "",
            "VendorName": "Enonic AS",
            "VendorUrl": "http://enonic.com",
            "Version": "2.0.0"
        }
    },
    "Failure": ""
}

CMS

Content metadata commands. Currently only one command present here:

Reprocess

Reprocesses content in the repository and regenerates metadata for the media attachments. Only content of a media type (super-type = base:media) are processed.

Unless the skipChildren flag is specified, it processes all descendants of the specified content path.

This command should be used after migrating content from Enonic CMS using the cms2xp tool.
Url
POST content/reprocess
Table 11. Params
Param Type Description

sourceBranchPath

String

target content path to be reprocessed. Format: <branch-name>:<content-path>. e.g draft:/

skipChildren

Boolean

flag to skip processing of content children

Response
{
    "Errors": [],
    "UpdatedContent": []
}

Repository

Commands for configuring and managing repositories.

Reindex

Reindex the content in the search indices for the given repository and branches. This is usually required after upgrades, and may be useful in many other situation.

Url
POST repo/index/reindex
Table 12. Params
Param Type Description

branches

String

a comma-separated list of branches to be reindexed

repository

String

the name of the repository to reindex

initialize

Boolean

if true, the indices will be deleted before recreated

Response
{
    "RepositoryId": "com.enonic.cms.default",
    "Branches": [
        "draft",
        "master"
    ],
    "NumberReindexed": 3,
    "StartTime": "2019-06-14T07:58:38.663Z",
    "EndTime": "2019-06-14T07:58:38.719Z",
    "Duration": "PT-0.056S"
}

Settings

Update settings for a specified repository.

Url
POST repo/index/updateSettings
Table 13. Params
Param Type Description

repositoryId

String

single repository to toggle read-only mode for

settings

JSON

settings object, see below

Available settings options
{
    "index": {
        "blocks.write": true, (1)
        "number_of_replicas": 3 (2)
    }
}
1 Toggle read-only mode.
2 Set the number of replicas in the cluster.
Response
{
    "UpdatedIndexes": [
        "search-com.enonic.cms.default",
        "storage-com.enonic.cms.default",
        "search-system-repo",
        "storage-system-repo"
    ]
}

List

List available repositories.

Url
GET repo/list
Response
{
    "Repositories": [
        {
            "Branches": [
                "master",
                "draft"
            ],
            "Id": "com.enonic.cms.default"
        },
        {
            "Branches": [
                "master"
            ],
            "Id": "system-repo"
        }
    ]
}

Vacuum

Deletes unused blobs and binaries from blobstore.

Make sure you have a backup of the installation available before doing a vacuum.
Url
POST system/vacuum
Response
{
{
    "TaskResults": [
        {
            "Deleted": 0,
            "Failed": 0,
            "InUse": 7,
            "Processed": 7,
            "TaskName": "UnusedSegmentsCleaner"
        },
        {
            "Deleted": 0,
            "Failed": 0,
            "InUse": 39,
            "Processed": 39,
            "TaskName": "UnusedVersionFilesCleaner"
        },
        {
            "Deleted": 0,
            "Failed": 0,
            "InUse": 2,
            "Processed": 2,
            "TaskName": "UnusedBinaryFilesCleaner"
        },
        {
            "Deleted": 0,
            "Failed": 0,
            "InUse": 123,
            "Processed": 123,
            "TaskName": "UnusedVersionTableEntryCleaner"
        }
    ]
}
}

Contents