A newer version of this documentation is available.

View Latest

Get Information on the Cluster

      +
      The Backup Service REST API allows information to be retrieved on a cluster’s active, archived, and imported repositories.

      HTTP Methods and URIs

      GET /cluster/self

      Description

      Returns a JSON document that contains subdocuments for active, imported, and archived repositories on the host cluster.

      Curl Syntax

      curl -X GET http://<backup-node-ip-address-or-domain-name>:8097/cluster/self
        -u <username>:<password>

      Only the host cluster (self) can be queried. The username and password must be those of a user with the Full Admin role.

      Responses

      Success returns 200 OK, and a JSON document that contains three subdocuments, which respectively correspond to the active, imported, and archived repositories on the cluster. The information in each subdocument includes an object for each repository. This object provides:

      • The id of the repository.

      • The name of the plan that the repository uses.

      • The name and uuid of the single bucket to which the plan is dedicated (unless the plan is dedicated to all buckets on the cluster).

      • The location of backed-up data on disk.

      • The names of the individual tasks within the plan; along with their task-type, and their next-scheduled time of running.

      If a cluster-name other than self is specified, 400 Bad Request is returned, with a message such as the following: {"status":400,"msg":"Remote clusters not supported","extras":"Invalid cluster: se3lf"}. If an incorrect URI is otherwise specified, 404 Object Not Found is returned, with a message such as the following: 404 Object Not Found.

      Failure to authenticate returns 401 Unauthorized. An internal error that prevents return of the repository-information returns 500 Internal Server Error.

      Examples

      The following call requests the list of repositories currently defined on the cluster:

      curl -v -X GET http://127.0.0.1:8091/_p/backup/api/v1/cluster/self \
      -u Administrator:password

      If successful, the call returns 200 OK, and an object whose initial part may appear as follows:

      {
        "name": "self",
        "imported": {
          "mergedRepo": {
            "id": "mergedRepo",
            "plan_name": "",
            "state": "imported",
            "archive": "/Users/user/Documents/mergedRepo",
            "repo": "7509894b-7138-40fe-917e-9581d298482c",
            "version": 1,
            "creation_time": "2020-09-17T10:15:39.025614+01:00",
            "update_time": "2020-09-17T10:15:39.025614+01:00"
          }
        },
        "archived": {},
        "active": {
          "hourlyBackupRepo": {
            "id": "hourlyBackupRepo",
            "plan_name": "hourlyBackupRepo",
            "bucket": {
              "name": "travel-sample",
              "uuid": "bf5e2d0ec35e7957ed96509b8ed7e13f"
            },
            "state": "paused",
            "archive": "/Users/user/Documents/backups/hourlyBackupRepo",
            "repo": "56f42a97-6c52-4e32-8597-b0bfed34af29",
            "running_one_off": {
              "restore-3034992d-5d1b-44d5-a9a3-a673b541f430": {
                "task_name": "restore-3034992d-5d1b-44d5-a9a3-a673b541f430",
                "status": "running",
                "start": "2020-09-16T11:06:47.089102+01:00",
                "end": "0001-01-01T00:00:00Z",
                "node_runs": [
                  {
                    "node_id": "1208b19a4d30e0b4c6af96b6448b4969",
                    "status": "running",
                    "start": "2020-09-16T11:06:47.087325+01:00",
                    "end": "0001-01-01T00:00:00Z",
                    "progress": 0,
                    "error_code": 0
                  }
                ],
                "error_code": 0,
                "type": "RESTORE",
                "target_cluster": "http://1270.0.1:8091"
              }
            },
            "version": 1,
            "health": {
              "healthy": false,
              "health_issue": "cannot verify bucket exists: bucket UUIDs don't match `bf5e2d0ec35e7957ed96509b8ed7e13f` != `15b15c78439db91ba73f27ac4d6ba116"
            },
            "creation_time": "2020-09-11T14:10:20.875345+01:00",
            "update_time": "2020-09-22T10:40:07.112184+01:00"
          },
          "testRepo": {
            "id": "testRepo",
            "plan_name": "_hourly_backups",
            "bucket": {
              "name": "travel-sample",
                    .
                    .
                    .

      The cluster is thus shown to contain a single imported repository, no archived repositories, and a number of active repositories, two of which can be identified in the fragment shown.

      See Also

      An overview of the Backup Service is provided in Backup Service. A step-by-step guide to using Couchbase Web Console to configure and use the Backup Service is provided in Manage Backup and Restore. Information on using the Backup Service REST API to create a repository is provided in Create a Repository.