[id='rest_v2_cluster_stop']
= Stopping {brandname} Clusters
Shut down entire {brandname} clusters with `POST` requests.

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/cluster?action=stop
----

{brandname} responds with `204 (No Content)` and then performs an orderly shutdown of
the entire cluster.


[id='rest_v2_stop_cluster_server']
= Stopping Specific {brandname} Servers in Clusters
Shut down one or more specific servers in {brandname} clusters with `GET`
requests and the `?action=stop&server` parameter.

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/cluster?action=stop&server={server1_host}&server={server2_host}
----

{brandname} responds with `204 (No Content)`.

[id='rest_v2_backup_cluster']
= Backing Up {brandname} Clusters
Create backup archives, `application/zip`, that contain resources (caches, templates, counters, Protobuf schemas, server tasks,
and so on) currently stored in the cache container for the cluster.

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/cluster/backups/{backupName}
----

Optionally include a JSON payload with your request that contains parameters
for the backup operation, as follows:

.JSON Parameters

|===
|Key |Required or Optional |Value

|`directory`
|OPTIONAL
|Specifies a location on the server to create and store the backup archive.

|===

If the backup operation successfully completes, the service returns `202 (Accepted)`.
If a backup with the same name already exists, the service returns  `409 (Conflict)`.
If the `directory` parameter is not valid, the service returns `400 (Bad Request)`.

[id='rest_v2_backup_cluster_list']
= Listing Backups
Retrieve the names of all backup operations that are in progress, completed, or
failed.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/cluster/backups
----

{brandname} responds with an Array of all backup names as in the following example:

[source,json,options="nowrap",subs=attributes+]
----
["backup1", "backup2"]
----

[id='rest_v2_backup_cluster_head']
= Checking Backup Availability
Verify that a backup operation is complete. A `200` response indicates the
backup archive is available. A `202` response indicates the backup operation is
in progress.

[source,options="nowrap",subs=attributes+]
----
HEAD /rest/v2/cluster/backups/{backupName}
----

[id='rest_v2_backup_cluster_get']
= Downloading Backup Archives
Download backup archives from the server. A `200` response indicates the
backup archive is available. A `202` response indicates the backup operation is
in progress.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/cluster/backups/{backupName}
----

[id='rest_v2_backup_cluster_delete']
= Deleting Backup Archives
Remove backup archives from the server. A `204` response indicates that the
backup archive is deleted. A `202` response indicates that the backup operation
is in progress but will be deleted when the operation completes.

[source,options="nowrap",subs=attributes+]
----
DELETE /rest/v2/cluster/backups/{backupName}
----

[id='rest_v2_restore_cluster']
= Restoring {brandname} Cluster Resources
Apply resources in a backup archive to restore {brandname} clusters. The provided
`{restoreName}` is for tracking restore progress, and is independent of the name of
backup file being restored.

[IMPORTANT]
====
You can restore resources only if the container name in the backup archive
matches the container name for the cluster.
====

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/cluster/restores/{restoreName}
----

A `202` response indicates that the restore request is accepted for processing.

== Restoring from Backup Archives on {brandname} Server
Use the `application/json` content type with your POST request to back up from
an archive that is available on the server.

.JSON Parameters

|===
|Key |Required or Optional |Value

|`location`
|REQUIRED
|Specifies the path of the backup archive to restore.

|`resources`
|OPTIONAL
|Specifies the resources to restore, in JSON format. The default is to restore all resources. If you specify one or more resources, then {brandname} restores only those resources. See the _Resource Parameters_ table for more information.

|===

include::backup_resources.adoc[]

The following example restores all counters from a backup archive on the server:

[source,json,options="nowrap",subs=attributes+]
----
include::json/rest_backup_restore_request_body.json[]
----

== Restoring from Local Backup Archives
Use the `multipart/form-data` content type with your POST request to upload a
local backup archive to the server.

.Form Data
|===
|Parameter |Content-Type |Required or Optional |Value

|`backup`
|`application/zip`
|REQUIRED
|Specifies the bytes of the backup archive to restore.
|===

.Example Request
----
Content-Type: multipart/form-data; boundary=5ec9bc07-f069-4662-a535-46069afeda32
Content-Length: 7798

--5ec9bc07-f069-4662-a535-46069afeda32
Content-Disposition: form-data; name="backup"; filename="testManagerRestoreParameters.zip"
Content-Type: application/zip
Content-Length: 7353

<zip-bytes>
--5ec9bc07-f069-4662-a535-46069afeda32--
----

[id='rest_v2_restore_cluster_list']
= Listing Restores
Retrieve the names of all restore requests that are in progress, completed, or
failed.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/cluster/restores
----

{brandname} responds with an Array of all restore names as in the following example:

[source,json,options="nowrap",subs=attributes+]
----
["restore1", "restore2"]
----

[id='rest_v2_restore_cluster_head']
= Checking Restore Progress
Verify that a restore operation is complete.

[source,options="nowrap",subs=attributes+]
----
HEAD /rest/v2/cluster/restores/{restoreName}
----

A `201 (Created)` response indicates the restore operation is completed.
A `202` response indicates the backup operation is in progress.

[id='rest_v2_restore_cluster_delete']
= Deleting Restore Metadata
Remove metadata for restore requests from the server. This action removes all metadata
associated with restore requests but does not delete any restored content. If you delete
the request metadata, you can use the request name to perform subsequent restore operations.

[source,options="nowrap",subs=attributes+]
----
DELETE /rest/v2/cluster/restores/{restoreName}
----

A `204` response indicates that the restore metadata is deleted.
A `202` response indicates that the restore operation is in progress and will be deleted when the operation
completes.

[id='rest_v2_cluster_distribution']
= Checking Cluster Distribution
Retrieve the distribution details about all servers in the {brandname} cluster.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/cluster?action=distribution
----

Returns a JSON array of each {brandname} server statistics in the cluster with the format:

[source,json,options="nowrap",subs=attributes+]
----
include::json/rest_cluster_distribution.json[]
----

Each element in the array represents an {brandname} node. If the statistics collection is
disabled, information about memory usage values is -1. The properties are:

* `node_name` is the node name.
* `node_addresses` is a list with all the node's physical addresses.
* `memory_available` the node available memory in bytes.
* `memory_used` the node used memory in bytes.
