A newer version of this documentation is available.

View Latest

Get Information on Repositories

      +
      The Backup Service REST API allows information to be retrieved on active, imported, or archived repositories.

      HTTP Methods and URIs

      GET /cluster/self/repository/< "active" | "imported" | "archived" >
      
      GET /cluster/self/repository/< "active" | "imported" | "archived" >/<repository-id>
      
      GET /cluster/self/repository/< "active" | "imported" | "archived" >/<repository-id>/info

      Description

      The GET /cluster/self/repository/< "active" | "imported" | "archived" > http method and URI return an array, each of whose members is an object containing information on a repository. Information includes repository names, file or cluster paths, and plan details.

      The GET /cluster/self/repository/< "active" | "imported" | "archived" >/<repository-id> http method and URI return a single object, containing information on the repository whose name is specified by the repository-id path-parameter. Information includes repository names, file or cluster paths, and plan details.

      The GET /cluster/self/repository/< "active" | "imported" | "archived" >/<repository-id>/info http method and URI return a single object, containing information on the repository whose name is specified by the repository-id path-parameter. Information includes backup names and dates, buckets, items, and mutations.

      Curl Syntax

      curl -X GET <backup-node-ip-address-or-domain-name>:8097/cluster/self/\
      repository/< "active" | "imported" | "archived" >
      -u <username>:<password>
      
      curl -X GET <backup-node-ip-address-or-domain-name>:8097/cluster/self/\
      repository/< "active" | "imported" | "archived" >/<repository-id>
      -u <username>:<password>
      
      curl -X GET <backup-node-ip-address-or-domain-name>:8097/cluster/self/\
      repository/< "active" | "imported" | "archived" >/<repository-id>/info
      -u <username>:<password>

      The repository-id path-parameter must be the name of a repository. The username and password must identify an administrator with the Full Admin role.

      Responses

      Successful location of all repositories returns 200 OK, and an array of repositories.

      Successful location of a specified repository returns 200 OK and an object containing information on the repository. If the specified repository is not located, 404 is returned, with the following object: {"status": 404, "msg": "no repositories found"}.

      If an internal error causes the call the fail, 500 is returned; with the message Could not retrieve the requested repository. Failure to authenticate returns 401 Unauthorized. An incorrectly specified URI returns 404 Object Not Found. An incorrectly specified method returns 404 Object Not Found, and returns the object {"status":404,"msg":"requested plan not found"}.

      Examples

      The following call returns information on all currently defined, active repositories,. Note that the output is piped to the jq command, to facilitate readability.

      curl -v -X GET \
      http://127.0.0.1:8097/api/v1/cluster/self/repository/active \
      -u Administrator:password  | jq

      Successful execution returns a JSON array, each of whose members is an object containing information on an active repository. Information includes repository names, file or cluster paths, and plan details. The initial part of the potentially extensive output might appear as follows:

      [
        {
          "id": "bestRepo",
          "plan_name": "BackupAndMergePlan",
          "state": "active",
          "archive": "/Users/user/Documents/archives/bestRepo",
          "repo": "40aa565c-6049-4ea9-9837-516a2dcdf53b",
          "scheduled": {
            "BackupEveryTuesdayForOneYear": {
              "name": "BackupEveryTuesdayForOneYear",
              "task_type": "BACKUP",
              "next_run": "2021-09-28T21:00:00+01:00"
            },
            "testTask3": {
              "name": "testTask3",
              "task_type": "MERGE",
              "next_run": "2020-10-29T22:00:00Z"
            }
          },
          "version": 1,
          "health": {
            "healthy": true
          },
          "creation_time": "2020-10-01T13:28:56.207976+01:00",
          "update_time": "2020-10-01T13:28:56.207976+01:00"
        },
        {
          "id": "testRepo",
          "plan_name": "_hourly_backups",
          "bucket": {
            "name": "travel-sample",
            "uuid": "15b15c78439db91ba73f27ac4d6ba116"
          },
            .
            .
            .

      Each object thus contains the id (name), plan_name, state, repo (unique identifier), and scheduled tasks for the repository. It also contains an account of the repository’s health, its creation time, and the time of its latest update.

      The following call returns information on a specific, named, active repository:

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

      If successful, the call returns the following object:

      {
        "id": "restRepo",
        "plan_name": "_hourly_backups",
        "bucket": {
          "name": "travel-sample",
          "uuid": "15b15c78439db91ba73f27ac4d6ba116"
        },
        "state": "active",
        "archive": "/Users/user/Documents/archives/restRepo",
        "repo": "8b623987-9353-48f0-9773-55b124ce9146",
        "scheduled": {
          "backup_hourly": {
            "name": "backup_hourly",
            "task_type": "BACKUP",
            "next_run": "2020-10-02T09:00:41+01:00"
          },
          "merge_every_6_hours": {
            "name": "merge_every_6_hours",
            "task_type": "MERGE",
            "next_run": "2020-10-02T12:30:48+01:00"
          },
          "merge_week": {
            "name": "merge_week",
            "task_type": "MERGE",
            "next_run": "2020-10-04T23:40:00+01:00"
          }
        },
        "version": 1,
        "health": {
          "healthy": true
        },
        "creation_time": "2020-09-29T10:48:52.232386+01:00",
        "update_time": "2020-09-29T10:48:52.232386+01:00"
      }

      The object thus contains information on the specified repository.

      The following call returns information including backup names and dates, buckets, items, and mutations; on an imported repository named mergedRepo:

      curl -v -X GET http://127.0.0.1:8097/api/v1/cluster/self/repository/imported/mergedRepo/info \
      -u Administrator:password  | jq

      If successful, the initial part of the potentially extensive output is as follows:

      {
        "name": "7509894b-7138-40fe-917e-9581d298482c",
        "size": 23859762,
        "count": 4,
        "backups": [
          {
            "date": "2020-09-16T09_00_29.113465+01_00",
            "type": "MERGE - FULL",
            "source": "Merge",
            "range": [
              "2020-09-16T08_00_25.672063+01_00",
              "2020-09-16T08_15_26.560952+01_00",
              "2020-09-16T08_30_27.458006+01_00",
              "2020-09-16T08_45_28.32018+01_00",
              "2020-09-16T09_00_29.113465+01_00"
            ],
            "events": 0,
            "fts_alias": 0,
            "size": 23806455,
            "buckets": [
              {
                "name": "travel-sample",
                "size": 23806449,
                "items": 31592,
                "mutations": 31592,
                "tombstones": 0,
                "views_count": 0,
                "fts_count": 0,
                "index_count": 10,
                "analytics_count": 0,
                "scopes": {
                  "0": {
                    "uid": 0,
                    "name": "_default",
                    "mutations": 31592,
                    "tombstones": 0,
                    "collections": {
                      "0": {
                        "id": 0,
                        "name": "_default",
                        "mutations": 31592,
                        "tombstones": 0
                      }
                    }
                  },
                  "8": {
                    "uid": 8,
                    "name": "MyScope",
                    "mutations": 0,
                    "tombstones": 0,
                    "collections": {
                      "8": {
                        "id": 8,
                        "name": "MyCollection",
                        "mutations": 0,
                        "tombstones": 0
                      }
                    }
                  }
                }
              }
            ],
            "complete": true,
            "source_cluster_uuid": "a7ec688d232620b2a9ea8c28ca68fd9a"
          },
          {
            "date": "2020-09-16T09_15_29.826312+01_00",
            "type": "INCR",
            "source": "http://127.0.0.1:8091",
            "events": 0,
            "fts_alias": 0,
            "size": 17769,
              .
              .
              .

      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 plan is provided in Create and Edit Plans. Information on using the Backup Service REST API to create a repository is provided in Create a Repository.