RESTful API to Manage Indexes

You can use the dotCMS REST API to manage indexes, performing all the same operations that are documented in the Managing Site Indexes with Elastic Search documentation. Note: You can verify the results of your REST API calls by viewing index information in the dotCMS backend.

User Authentication#

---

All of the following examples assume the server is running on localhost:8082, and the user has been authenticated on your dotCMS instance as a user with permissions to modify the indexes.

In all of the following example commands:

• Replace localhost:8082 with the domain name and port of your dotCMS instance.
• Provide actual values where optional values are indicated (in square brackets).
• You can also authenticate users using standard dotCMS REST API authentication (passing user and password as parameters, or using cookie based sessions).
• Admin passwords are assumed to be admin, as on the demo site and starters prior to version 22.06. For versions 22.06 or later, this is no longer the default; now, admin passwords default to a random string generated on first startup and displayed in the server logs. This starter password can also be pre-configured through the DOT_INITIAL_ADMIN_PASSWORD environment variable.

Snapshot an Index #

---

The following curl command downloads an index with name live_20160925211511:

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/snapshot/index/live_20160925211511 > live_20160925211511.zip

Restore an Index Snapshot#

---

The following example restores an index which was previously downloaded.

Note:

• The index to be restored must be sent in zip format.
• Some browsers, such as Safari, may automatically extract the downloaded zip files, so you must make sure to send a zipped version of the downloaded index.

curl --user admin@dotcms.com:admin -F file=@live_20160925211511.zip  -XPOST http://localhost:8082/api/v1/esindex/restoresnapshot/

Download an Index (Deprecated — See Snapshot an Index) #

---

The following curl command downloads an index with name working_20130628092243:

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/download/index/working_20130628092243 > file.zip

To download the current live or working index, pass live or working, respectively, as the index name.

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/download/index/live > live.zip

Restore an Index (Deprecated — See Restore an Index Snapshot){#Restore}#

---

The following example restores an index which was previously downloaded.

Note:

• The index to be restored must be sent in zip format.
• Some browsers, such as Safari, may automatically extract the downloaded zip files, so you must make sure to send a zipped version of the downloaded index.

The URI parameter clear deletes all the documents in the index before restoring (completely overwriting the existing index with the index being restored). This parameter defaults to false.

curl --user admin@dotcms.com:admin -F file=@file.zip  -XPUT http://localhost:8082/api/v1/esindex/restore/index/working_20130705193521/clear/true

Create an Index (Deprecated — See Snapshot an Index)#

---

/api/v1/esindex/create[/parameters]

Parameters

Response:

The name of the new index in text/plain format.

Example 1#

The following curl command creates a new working index with 2 shards and a default index name:

Command:#

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/create/live/false/shards/2

Response:#

live_20130707211119

Example 2#

The following curl command creates a new live index with 2 shards and a custom index name:

Command:#

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/create/live/true/shards/2/index/fandango

Response:#

live_fandango

Reindex#

---

Updates an existing index. Usage:

/api/v1/esindex/reindex?{parameter=this&other_parameter=that}

Depending on the HTTP method employed, this can perform one of the following operations, with the associated parameters.

• Retrieve reindexation progress (via GET)

  Param	Type
  filter	string
  page	int
  per_page	int

• Start a reindex (via POST)

  Param	Type
  shards	int
  contentType	string

• Stop a reindex (via DELETE)

Example 1: Getting Reindexation Progress#

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/reindex?filter=news&page=4

Example 2: Starting a Reindex#

curl --user admin@dotcms.com:admin -XPOST http://localhost:8082/api/v1/esindex/reindex?shards=-15283749&contentType=DOTALL

Example 3: Halting a Reindex#

curl --user admin@dotcms.com:admin -XDELETE http://localhost:8082/api/v1/esindex/reindex

Clear an Index#

---

Clears all contents out of the specified index (but does not delete the index).

/api/v1/esindex/clear/index/[index_name]

Example#

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/clear/index/working_20130707223633

Delete an Index#

---

Deletes the specified index.

Example#

curl --user admin@dotcms.com:admin -XDELETE http://localhost:8082/api/v1/esindex/index/working_20130707223633

Activate an Index#

---

When used on a content index, sets the specified index to the active index. When used on a sitesearch index, makes the specified index the default index.

Example#

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/activate/index/working_20130707233404

Deactivate an Index#

---

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/deactivate/index/working_20130707233404

Update Replica#

---

Duplicates the specified index. The number of copies of an index in a cluster is equal to the number of replicas plus one; so, for example, if there is 1 replica then there will be 2 copies of the index in the cluster.

Special Note: This API command requires the Manual Cluster Configuration settings, otherwise the command is automatically disabled.

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/updatereplica/index/working_20130707233404/replicas/1

Close an Index#

---

Closes file descriptors and releases memory used to operate over the index. After this operation is performed, the index will not be available for queries until it is reopened with the open operation. This operation allows you to stop using an index without deleting it; however a closed index will still take up the full amount of drive space of a normal index.

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/close/index/working_20130707233404

Open an Index#

---

Re-open an index which has been closed.

curl --user admin@dotcms.com:admin -XPUT http://localhost:8082/api/v1/esindex/open/index/working_20130707233404

Get Active Index#

---

Returns the name of the current live or working index.

The working index (note the "type" parameter)

Example: Get Current Working Index#

Command:#

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/active/type/working

Response:#

working_20130628092243

Example: Get Current Live Index#

Command:#

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/active/type/live

Response:#

live_20130628092243

Get Document Count#

---

Returns the number of documents stored in the specified index.

Example#

Command:#

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/docscount/index/working_20130628092243

Response:#

654

List Indices#

---

Returns a list of all indices on the system. Uses json format, which can be easily parsed with the JSONTool.

Example#

Command:#

curl --user admin@dotcms.com:admin -XGET http://localhost:8082/api/v1/esindex/indexlist/

Response:#

["live_20130707233408","working_20130707233404","working_20130628092243","live_20130628092243"]