Create and Edit Plans

The Backup Service REST API allows plans to be created and edited. A plan specifies one or more tasks. Once created, a plan can be used in the creation of a repository.

HTTP Methods and URIs

POST /plan/<new-plan-id>

PUT /plan/<existing-plan-id>

The new-plan-id must be a plan-name that is unique across the cluster. The POST method creates a new plan, so named. The PUT method edits an existing plan of the name specified by existing-plan-id.

Description

A plan, once defined, is used in the creation of a repository; thereby allowing data from the cluster to be regularly backed up and, if appropriate, allowing existing backups to be periodically merged.

Note that merges are supported for filesystem-based repositories, but are not supported for cloud-based repositories. If a merge is scheduled for a cloud-based repository, the Backup Service skips the task.

A plan is defined by being specified as the JSON payload to the POST /plan/<new-plan-id> http method and URI. An existing plan can be edited by means of the PUT /plan/<existing-plan-id> http method and URI: the complete, new specification for the plan being specified as the JSON payload.

Curl Syntax

curl -X POST http://<backup-node-ip-address-or-domain-name>:8097/plan/<new-plan-id>
  -u <username>:<password>
  -d <plan-description>

curl -X PUT http://<backup-node-ip-address-or-domain-name>:8097/plan/<existing-plan-id>
  -u <username>:<password>
  -d <plan-description>

The username and password must be those of a user with the Full Admin role.

The plan-description contains the following:

A plan-name that is unique across the cluster.
An optional description of the plan.
An array containing the Couchbase Services whose data is to be backed up.
An array. This may be empty, or may contain one or more tasks. Each specified task contains the following:
- A task-name that is unique across the plan.
- The type of the task, which can be BACKUP or MERGE.
- Whether the task should be a full backup or not: a full backup (rather than an incremental backup), can only be specified as true when the task-type is BACKUP; otherwise, a full backup must be specified as null.
- The schedule for the task, containing the following:
  - The type of job, which must correspond to the task-type, BACKUP or MERGE.
  - The period of the task, which can be either of the following:
  - One of the following time-units: MINUTES, HOURS, DAYS, WEEKS.
  - A weekday, such as MONDAY, TUESDAY, WEDNESDAY, etc.
  - The frequency of the task, which can be an integer between 1 and 200, inclusive. If the task specifies a time-unit, the frequency indicates the number of time-units that must elapse between each repetition of the task: for example, 20 and MINUTES means that the task is to be performed once every twenty minutes. If the task specifies a weekday, the frequency indicates for how many instances of the weekday the task should continue to be performed, once per day: for example, 20 and TUESDAY means that the task is to be performed once every Tuesday for the next twenty Tuesdays.
  - A time at which the task is to be performed, each day. This is only to be specified when a weekday is used: in such cases, the task will be performed once on the specified weekday, at the specified time.
- Additional options for the task. If the task is a backup, the value must be null. If the task is a merge, the value must an object, featuring an offset start and offset end, specified as integers. The start indicates the most recent, and the end indicates the least recent day whose backups are to be merged: therefore 0 and 2 indicate that the backups to be merged are those for today, yesterday, and the day before yesterday.

Syntactically therefore, the plan-description is as follows:

{
  "name": <test-plan-name>,
  "description": <test-plan-description>,
  "services": [ < "data" | "gsi" | "views" | "ft" | "eventing" | "cbas" > ],
  "tasks": [
    {
      "name": <task-name>,
      "task_type": < "BACKUP" | "MERGE" >,
      "full_backup": < "null" | "true" >,
      "schedule": {
        "job_type": < "BACKUP" | "MERGE" >,
        "frequency": <integer-from-1-to-200-inclusive>,
        "period":
          < "MINUTES" | "HOURS" | "DAYS" | "WEEKS" > |
            < "MONDAY" | "TUESDAY" | "WEDNESDAY" | "THURSDAY" |
              "FRIDAY" | "SATURDAY" | "SUNDAY" >
      }
      "options": < "null" | "true" >
    }
  ]
}

Responses

Successful plan-creation returns 200 OK; with the message, The plan was created. An incorrectly specified plan returns 400; with the message, The plan was not valid. An internal error returns 500; with the message, Could not add the plan due to an internal error.

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 example creates a plan for performing weekly full backups, and monthly merges, for one year. Formatted, the plan is as follows:

{
  "name": "BackupAndMergePlan",
  "description": "A plan for backing up and merging.",
  "services": [
    "data"
  ],
  "tasks": [
    {
      "name": "BackupEveryTuesdayForOneYear",
      "task_type": "BACKUP",
      "schedule": {
        "job_type": "BACKUP",
        "frequency": 1,
        "period": "TUESDAY",
        "time": "22:00"
      },
      "options": null,
      "full_backup": true
    },
    {
      "name": "MergeOncePerMonth",
      "task_type": "MERGE",
      "full_backup": null,
      "schedule": {
        "job_type": "MERGE",
        "frequency": 4,
        "period": "WEEKS",
        "time": "22:00"
      },
      "options": {
        "offset_start": 0,
        "offset_end": 28
      }
    }
  ]
}

The plan is thus named BackupAndMergePlan and specifies that data from the Data Service alone be handled. The plan features two tasks. The first, BackupEveryTuesdayForOneYear specifies that a full backup be perfomed every Tuesday, at 22:00. The second, MergeOncePerMonth, specifies that a merge occur every four weeks, and that all builds that have occurred from the current day back to 28 days ago be included.

The call is executed as follows:

curl -v -X POST http://127.0.0.1:8097/api/v1/plan/BackupAndMergePlan \
-u Administrator:password \
-d '{"name": "BackupAndMergePlan","description": "A plan for backing up and merging.","services": ["data"],"tasks": [{"name": "BackupEveryTuesdayForOneYear","task_type": "BACKUP","schedule": {"job_type": "BACKUP","frequency": 1,"period": "TUESDAY","time": "22:00"},"options": null,"full_backup": true},{"name": "testTask3","task_type": "MERGE","full_backup": null,"schedule": {"job_type": "MERGE","frequency": 4,"period": "WEEKS","time": "22:00"},"options": {"offset_start": 0,"offset_end":28}}]}'

If the call is successful, 200 OK is returned.

The following use of the PUT method modifies the existing plan, specifying a backup time of 21:00:

curl -v -X PUT http://127.0.0.1:8097/api/v1/plan/BackupAndMergePlan \
-u Administrator:password \
-d '{"name": "BackupAndMergePlan","description": "A plan for backing up and merging.","services": ["data"],"tasks": [{"name": "BackupEveryTuesdayForOneYear","task_type": "BACKUP","schedule": {"job_type": "BACKUP","frequency": 1,"period": "TUESDAY","time": "21:00"},"options": null,"full_backup": true},{"name": "testTask3","task_type": "MERGE","full_backup": null,"schedule": {"job_type": "MERGE","frequency": 4,"period": "WEEKS","time": "22:00"},"options": {"offset_start": 0,"offset_end":28}}]}'

Again, if the call is successful, 200 OK is returned.