Backup Service API v1

Backup Service API v1

Backups (backups)

Backups allow users to record their backups and metadata information about those backups and when backups were taken. It holds the backup information.

GET
/v1/backups

Lists backups

Lists backups.

This operation lists backups for the project.

Normal response codes: 200

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

search (Optional)

body

dict

The query option of list. It is a JSON structure. It contains the keywords match, match_not, or one of the two. The values about keys match and match_not are a list of {key, value}.

Response Parameters

Name

In

Type

Description

backups (Optional)

body

list

A list of backups.

Request Example

{
    "match_not": [
        {
            "storage": "ftps"
        }
    ],
    "match": [
        {
            "backup_name": "freezer_mysql_backup"
        }
    ]
}

Response Example

{
  "backups": [
    {
      "backup_id": "96a5946a6e994a38a3d1008fbc6f3406",
      "user_id": "a387de3311484ce58c4560486bc153f1",
      "job_id": "df96800d16fc4d28af75c8451daf0a92",
      "backup_metadata": {
        "ssh_port": 22,
        "curr_backup_level": 0,
        "backup_name": "freezer_mysql_backup",
        "container": "freezer_database_backups",
        "compression": "gzip",
        "dry_run": "",
        "hostname": "backup-node1",
        "storage": "swift",
        "vol_snap_path": "\/var\/lib\/freezer_81856317d419498cb95f3bdffc847361\/.",
        "os_auth_version": "",
        "client_os": "linux2",
        "time_stamp": 1486660214,
        "container_segments": "",
        "ssh_username": "",
        "path_to_backup": "\/var\/lib\/freezer_81856317d419498cb95f3bdffc847361\/.",
        "ssh_key": "",
        "proxy": "",
        "always_level": "",
        "max_level": 14,
        "backup_media": "fs",
        "ssh_host": "",
        "mode": "mysql",
        "fs_real_path": "\/var\/lib\/mysql\/",
        "action": "backup",
        "client_version": "2.0.2",
        "log_file": "\/root\/.freezer\/freezer.log"
      },
      "client_id": "backup-node1",
      "backup_uuid": "9598dd99e1ce42019e498c5493ae1f84",
      "user_name": "os_backup"
    },
    {
      "backup_id": "0cd44caf6db5486b94a04b33256a5ff4",
      "user_id": "a387de3311484ce58c4560486bc153f1",
      "job_id": "b30efac3ef744c45bf3062775ea3525b",
      "backup_metadata": {
        "ssh_port": 22,
        "curr_backup_level": 0,
        "backup_name": "freezer_mysql_backup",
        "container": "freezer_database_backups",
        "compression": "gzip",
        "dry_run": "",
        "hostname": "backup-node1",
        "storage": "swift",
        "vol_snap_path": "\/var\/lib\/freezer_c5d4504387f84b1e96266b6f00bf5f04\/.",
        "os_auth_version": "",
        "client_os": "linux2",
        "time_stamp": 1486660222,
        "container_segments": "",
        "ssh_username": "",
        "path_to_backup": "\/var\/lib\/freezer_c5d4504387f84b1e96266b6f00bf5f04\/.",
        "ssh_key": "",
        "proxy": "",
        "always_level": "",
        "max_level": 14,
        "backup_media": "fs",
        "ssh_host": "",
        "mode": "mysql",
        "fs_real_path": "\/var\/lib\/mysql\/",
        "action": "backup",
        "client_version": "2.0.2",
        "log_file": "\/root\/.freezer\/freezer.log"
      },
      "client_id": "backup-node1",
      "backup_uuid": "2ba51cb9eff543d4b9a530b3c0d2f7cc",
      "user_name": "os_backup"
    }
  ]
}
GET
/v1/backups/{backup_id}

Show backups

Show backups.

This operation shows a certain backup . It displays all backup details.

Normal response codes: 200

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

backup_id

query

string

The UUID of the backup.

Response Parameters

Name

In

Type

Description

user_id

body

string

The user UUID.

backup_id

body

string

The UUID of the backup.

user_name

body

string

The username.

backup_metadata

body

list

A list of backup metada information. This contains the backup details. like path_to_backup, backup_name, hostname, job_id, storage, …

Response Example

{
        "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
        "backup_id": "96a5946a6e994a38a3d1008fbc6f3406",
        "user_name": "demo",
        "backup_metadata":
        {
            "ssh_port": 22,
            "consistency_checksum": "",
            "curr_backup_level": 0,
            "backup_name": "test0001_backup",
            "container": "/tmp/test0001_container",
            "compression": "gzip",
            "dry_run": "",
            "hostname": "szaher",
            "storage": "local",
            "vol_snap_path": "/etc/",
            "os_auth_version": "",
            "client_os": "linux2",
            "time_stamp": 1493052022,
            "container_segments": "",
            "ssh_username": "",
            "path_to_backup": "/etc/",
            "ssh_key": "",
            "proxy": "",
            "job_id": "0ae284d514eb47dd84154748b5056749",
            "always_level": "",
            "max_level": "",
            "backup_media": "fs",
            "ssh_host": "",
            "mode": "fs",
            "fs_real_path": "/etc/",
            "action": "backup",
            "client_version": "5.0.0",
            "log_file": "/home/saad/job0001.log"
        },
        "_version": 1
}
DELETE
/v1/backups/{backup_id}

Delete backups

Delete backups.

This operation deletes a certain backup .

Normal response codes: 204

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

backup_id

query

string

The UUID of the backup.

There is no response for this operation.

Jobs (jobs)

Jobs allow users to schedule and execute backup jobs on one node or more. Jobs are stored through the api in the database. Every job contains set of actions that carry out the backup job.

GET
/v1/jobs

Lists jobs

Lists jobs.

This operation lists jobs for the project.

Normal response codes: 200

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

search (Optional)

body

dict

The query option of list. It is a JSON structure. It contains the keywords match, match_not, or one of the two. The values about keys match and match_not are a list of {key, value}.

Response Parameters

Name

In

Type

Description

jobs (Optional)

body

list

A list of jobs.

Request Example

{
    "match_not": [
        {
            "schedule_interval": "10 days"
        }
    ],
    "match": [
        {
            "client_id": "752d8bd43d654e7a840bbfda77ce41af_szaher"
        }
    ]
}

Response Example

{
        "jobs":
        [
            {
                "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
                "description": "Test-0001",
                "job_schedule":
                {
                    "schedule_interval": "50 minutes",
                    "status": "scheduled",
                    "time_started": 1493055141,
                    "time_created": 1493051865,
                    "time_ended": 1493055142,
                    "result": "success",
                    "current_pid": 16793,
                    "event": ""
                },
                "client_id": "752d8bd43d654e7a840bbfda77ce41af_szaher",
                "job_actions":
                [
                    {
                        "freezer_action":
                        {
                            "backup_name": "test0001_backup",
                            "container": "/tmp/test0001_container",
                            "no_incremental": true,
                            "path_to_backup": "/etc/",
                            "storage": "local",
                            "log_file": "/home/saad/job0001.log",
                            "snapshot": false,
                            "action": "backup",
                            "remove_older_than": 365
                        },
                        "max_retries": 5,
                        "max_retries_interval": 6,
                        "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
                        "action_id": "280d51d041ce4d4da8a386e96263f759"
                    }
                ],
                "job_id": "0ae284d514eb47dd84154748b5056749"
            }
        ]
}
POST
/v1/jobs

Creates job

Creates a job.

This operation creates a new job.

The body attribute specifies contains a set of actions that gets created

one the job is submitted.

The description is the name that you give to the job. The name must not exceed 64 bytes in length.

The job_schedule is very important to schedule the job or it will run only once. also you can provide event which can automatically start/stop the job.

The job_actions the actual backup or restore action to be done.

Normal response codes: 201

Error response codes:

  • Syntax Error (753)

  • BadRequest (400)

  • Unauthorized (401)

  • ServiceUnavailable (503)

Request Parameters

Name

In

Type

Description

description

body

string

The name of the job.

job_schedule

body

dict

The schedule information of the job.

job_actions

body

list

A list of actions that carry out the backup/restore job.

Request Example

{
    "description": "Test-0001",
    "job_schedule": {
        "schedule_interval": "5 minutes",
        "status": "scheduled",
        "event": "start"
    },
    "job_actions": [
        {
            "max_retries": 5,
            "max_retries_interval": 6,
            "freezer_action": {
                "backup_name": "test0001_backup",
                "container": "test0001_container",
                "no_incremental": true,
                "path_to_backup": "/etc/",
                "log_file": "/home/saad/job0001.log",
                "snapshot": true,
                "action": "backup",
                "remove_older_than": 365
            }
        }
]
}

This operation does not return a response body.

GET
/v1/jobs/{job_id}

Show jobs

Shows jobs.

This operation shows a certain job. It displays all job details with actions inside the job.

Normal response codes: 200

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

job_id

query

string

The job UUID.

Response Parameters

Name

In

Type

Description

user_id

body

string

The user UUID.

description

body

string

The name of the job.

job_schedule

body

dict

The schedule information of the job.

client_id

body

string

The client UUID.

job_actions

body

list

A list of actions that carry out the backup/restore job.

job_id

body

string

The job UUID.

Response Example

{
        "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
        "description": "Test-0001",
        "_version": 83,
        "job_schedule":
        {
            "schedule_interval": "2 minutes",
            "status": "scheduled",
            "time_started": 1493119341,
            "time_created": 1493051865,
            "time_ended": 1493119342,
            "result": "success",
            "current_pid": 10058,
            "event": ""
        },
        "client_id": "752d8bd43d654e7a840bbfda77ce41af_szaher",
        "project_id": "752d8bd43d654e7a840bbfda77ce41af",
        "job_actions":
        [
            {
                "freezer_action":
                {
                    "backup_name": "test0001_backup",
                    "container": "/tmp/test0001_container",
                    "no_incremental": true,
                    "path_to_backup": "/etc/",
                    "storage": "local",
                    "log_file": "/home/saad/job0001.log",
                    "snapshot": false,
                    "action": "backup",
                    "remove_older_than": 365,
                    "project_id": "752d8bd43d654e7a840bbfda77ce41af"
                },
                "max_retries": 5,
                "max_retries_interval": 6,
                "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
                "action_id": "280d51d041ce4d4da8a386e96263f759"
            }
        ],
        "job_id": "0ae284d514eb47dd84154748b5056749"
}
PATCH
/v1/jobs/{job_id}

Updates jobs

Updates a job.

This operation creates a new job.

The body attribute specifies contains a set of actions that gets updated

once the job is submitted.

The description is the name that you give to the job. The name should not exceed 64 bytes in length.

The job_schedule is very important to schedule the job or it will run only once. also you can provide event which can automatically start/stop the job.

The job_actions the actual backup or restore action to be done.

Normal response codes: 201

Error response codes:

  • Syntax Error (753)

  • BadRequest (400)

  • Unauthorized (401)

  • ServiceUnavailable (503)

Query Parameters

Name

In

Type

Description

job_id

query

string

The job UUID.

Request Parameters

Name

In

Type

Description

description

body

string

The name of the job.

job_schedule

body

dict

The schedule information of the job.

job_actions

body

list

A list of actions that carry out the backup/restore job.

Request Example

{
    "description": "Test-0001",
    "job_schedule": {
        "schedule_interval": "5 minutes",
        "status": "scheduled",
        "event": "stop"
    },
    "project_id": "752d8bd43d654e7a840bbfda77ce41af",
    "job_actions": [
        {
            "max_retries": 10,
            "max_retries_interval": 10,
            "freezer_action": {
                "backup_name": "test0001_backup",
                "container": "/tmp/xyzxyzxyz",
                "storage": "local",
                "no_incremental": true,
                "path_to_backup": "/etc/",
                "log_file": "/home/saad/job0001.log",
                "snapshot": false,
                "action": "backup",
                "remove_older_than": 365,
                "project_id": "752d8bd43d654e7a840bbfda77ce41af"
            }
        }
]
}

Response Example

{"job_id": "0ae284d514eb47dd84154748b5056749", "version": "3"}
DELETE
/v1/jobs/{job_id}

Delete jobs

Delete jobs.

This operation deletes a certain job .

Normal response codes: 204

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

job_id

query

string

The job UUID.

There is no response for this operation.

Clients (clients)

Clients allow freezer schedulers or users to create a client to be able to create, update, show or delete job. The client is required to record you backups on freezer api.

GET
/v1/clients

Lists clients

Lists clients.

This operation lists clients.

Normal response codes: 200

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

search (Optional)

body

dict

The query option of list. It is a JSON structure. It contains the keywords match, match_not, or one of the two. The values about keys match and match_not are a list of {key, value}.

Response Parameters

Name

In

Type

Description

clients

body

list

A list of clients.

Request Example

{
    "match_not": [
        {
            "client_id": "tecs_node1"
        }
    ],
    "match": [
        {
            "user_id":"0cd44caf6db5486b94a04b33256a5ff4"
        }
    ]
}

Response Example

{
        "clients":
        [
            {
                "client":
                {
                    "client":
                    {
                        "hostname": "szaher01",
                        "uuid": "c4031a4885384376a717a238de975a9c"
                    },
                    "user_id": "5cd44cafcdb5386b94a04b33d56a5ff6",
                    "uuid": "6f588392aa864c96b4af96a4eae005ce",
                    "client_id": "752d8bd43d654e7a840bbfda77ce41af_szaher01"
                },
                "user_id": "0cd44caf6db5486b94a04b33256a5ff4"
            },
            {
                "client":
                {
                    "hostname": "szaher",
                    "uuid": "c4031a9885384376a717a238ae975d9b",
                    "client_id": "752d8bd43d654e7a840bbfda77ce41af_szaher"
                },
                "user_id": "0cd44caf6db5486b94a04b33256a5ff4"
            }
        ]
}
POST
/v1/clients

Creates Client

Creates a client.

This operation creates a new client.

Normal response codes: 201

Error response codes:

  • Syntax Error (753)

  • BadRequest (400)

  • Unauthorized (401)

  • ServiceUnavailable (503)

Request Parameters

Name

In

Type

Description

hostname

body

string

The hostname of the machine that client is running on.

uuid

body

string

The client UUID.

client_id

body

string

The client UUID.

Request Example

{
            "client":
            {
                "hostname": "szaher01",
                "uuid": "c4031a4885384376a717a238de975a9c"
            },
            "client_id": "752d8cd43d654e7a840bbfd277ce41af_szaher01"
}

Response Parameters

Name

In

Type

Description

client_id

body

string

The client UUID.

Response Example

{"client_id": "752d8cd43d654e7a840bbfd277ce41af_szaher01"}
GET
/v1/clients/{client_id}

Show clients

Show clients.

This operation shows a certain client . It displays all client details.

Normal response codes: 200

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

client_id

query

string

The client ID.

Response Parameters

Name

In

Type

Description

user_id

body

string

The user UUID.

client_id

body

string

The client UUID.

hostname

body

string

The hostname of the machine that client is running on.

uuid

body

string

The client UUID.

Response Example

{
        "client":
        {
            "client":
            {
                "hostname": "szaher01",
                "uuid": "c4031a4885384376a717a238de975a9c"
            },
            "user_id": "5cd44cafcdb5386b94a04b33d56a5ff6",
            "uuid": "6f588392aa864c96b4af96a4eae005ce",
            "client_id": "752d8bd43d654e7a840bbfda77ce41af_szaher01"
        },
        "user_id": "0cd44caf6db5486b94a04b33256a5ff4"
}
DELETE
/v1/clients/{client_id}

Delete clients

Delete clients.

This operation deletes a certain client.

Normal response codes: 204

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

client_id

query

string

The client ID.

There is no response for this operation.

Actions (actions)

Actions allow users to execute backups and restore operations on one node or more. Actions are stored through the api in the database. It is included in the job, every job contains set of actions that carry out the backup/restore job.

GET
/v1/actions

Lists Actions

Lists actions.

This operation lists actions.

Normal response codes: 200

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

search (Optional)

body

dict

The query option of list. It is a JSON structure. It contains the keywords match, match_not, or one of the two. The values about keys match and match_not are a list of {key, value}.

Response Parameters

Name

In

Type

Description

actions

body

list

A list of actions.

Request Example

{
    "match_not": [
        {
            "max_retries": 20
        }
    ],
    "match": [
        {
            "backup_name": "test0001_backup"
        }
    ]
}

Response Example

{
        "actions":
        [
            {
                "freezer_action":
                {
                    "backup_name": "test0001_backup",
                    "container": "test0001_container",
                    "no_incremental": true,
                    "path_to_backup": "/etc/",
                    "project_id": "752d8bd43d654e7a840bbfda77ce41af",
                    "snapshot": true,
                    "action": "backup",
                    "remove_older_than": 365,
                    "log_file": "/home/saad/job0001.log"
                },
                "max_retries": 5,
                "max_retries_interval": 6,
                "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
                "action_id": "061f7657350a4bddbfabf8d2a25dad96"
            },
            {
                "freezer_action":
                {
                    "backup_name": "test0001_backup",
                    "container": "/tmp/test0001_container",
                    "no_incremental": true,
                    "path_to_backup": "/etc/",
                    "storage": "local",
                    "project_id": "752d8bd43d654e7a840bbfda77ce41af",
                    "snapshot": false,
                    "action": "backup",
                    "remove_older_than": 365,
                    "log_file": "/home/saad/job0001.log"
                },
                "max_retries": 5,
                "max_retries_interval": 6,
                "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
                "action_id": "317f8bc1fbbe49819d1b60f4b4387e63"
            }
        ]
}
POST
/v1/actions

Creates action

Creates an action.

This operation creates a new action.

The body attribute specifies contains a set of actions that gets created

one the job is submitted.

The description is the name that you give to the job. The name must not exceed 64 bytes in length.

The job_schedule is very important to schedule the job or it will run only once. also you can provide event which can automatically start/stop the job.

The freezer_action holds the actual action parameters. freezer_action differs from action to another as it depends what this action is doing (backup, restore, admin, info)

Normal response codes: 201

Error response codes:

  • Syntax Error (753)

  • BadRequest (400)

  • Unauthorized (401)

  • ServiceUnavailable (503)

Request Parameters

Name

In

Type

Description

freezer_action

body

dict

Action parameters. It depends on the actual action (backup, restore, admin, info) so the parameters differ.

max_retries (Optional)

body

int

A number of times freezer should retry to execute the action.

max_retries_interval (Optional)

body

int

The time that freezer should wait between diferrent retrials to execute the action.

Request Example

{
            "freezer_action":
            {
                "backup_name": "production_backup",
                "container": "prod_container",
                "no_incremental": true,
                "path_to_backup": "/etc/",
                "snapshot": true,
                "action": "backup",
                "remove_older_than": 365,
                "log_file": "/var/log/freezer/job0001.log"
            },
            "max_retries": 5,
            "max_retries_interval": 6
}

Response Parameters

Name

In

Type

Description

action_id

body

string

The action UUID.

Response Example

{
        "action_id": "1fc414f091b84263b45d7e1f1f85e5bf"
}
GET
/v1/actions/{action_id}

Show actions

Shows actions.

This operation shows a certain action. The action details.

Normal response codes: 200

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

action_id

query

string

The action UUID.

Response Parameters

Name

In

Type

Description

freezer_action

body

dict

Action parameters. It depends on the actual action (backup, restore, admin, info) so the parameters differ.

max_retries (Optional)

body

int

A number of times freezer should retry to execute the action.

max_retries_interval (Optional)

body

int

The time that freezer should wait between diferrent retrials to execute the action.

user_id

body

string

The user UUID.

action_id

body

string

The action UUID.

Response Example

{
        "freezer_action":
        {
            "backup_name": "production_backup",
            "container": "prod_container",
            "no_incremental": true,
            "path_to_backup": "/etc/",
            "snapshot": true,
            "action": "backup",
            "remove_older_than": 365,
            "log_file": "/var/log/freezer/job0001.log"
        },
        "max_retries_interval": 6,
        "_version": 1,
        "max_retries": 5,
        "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
        "action_id": "1fc414f091b84263b45d7e1f1f85e5bf"
}
POST
/v1/actions/{action_id}

Updates actions

Updates an action.

This operation updates or replaces an existing action.

Normal response codes: 201

Error response codes:

  • Syntax Error (753)

  • BadRequest (400)

  • Unauthorized (401)

  • ServiceUnavailable (503)

Query Parameters

Name

In

Type

Description

action_id

query

string

The action UUID.

Request Parameters

Name

In

Type

Description

freezer_action

body

dict

Action parameters. It depends on the actual action (backup, restore, admin, info) so the parameters differ.

max_retries (Optional)

body

int

A number of times freezer should retry to execute the action.

max_retries_interval (Optional)

body

int

The time that freezer should wait between diferrent retrials to execute the action.

action_id

body

string

The action UUID.

Request Example

{
            "freezer_action":
            {
                "backup_name": "production_backup",
                "container": "prod_container",
                "no_incremental": true,
                "path_to_backup": "/etc/",
                "snapshot": true,
                "action": "backup",
                "remove_older_than": 365,
                "log_file": "/var/log/freezer/job0001.log"
            },
            "max_retries": 5,
            "max_retries_interval": 6
}

Response Example

{
  "version": 2,
  "action_id": "1fc414f091b84263b45d7e1f1f85e5bf"
}
DELETE
/v1/actions/{action_id}

Delete actions

Delete actions.

This operation deletes a certain action.

Normal response codes: 204

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

action_id

query

string

The action UUID.

There is no response for this operation.

Sessions (sessions)

A session is a group of jobs which share the same scheduling time. A session is identified by its session_id and has a numeric tag (session_tag) which is incremented each time that a new session is started. The purpose of the session_tag is that of identifying a group of jobs which have been executed together and which therefore represent a snapshot of a distributed system.

When a job is added to a session, the scheduling time of the session is copied into the job data structure, so that any job belonging to the same session will start at the same time.

GET
/v1/sessions

Lists Sessions

Lists sessions.

This operation lists sessions.

Normal response codes: 200

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

offset (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

search (Optional)

body

dict

The query option of list. It is a JSON structure. It contains the keywords match, match_not, or one of the two. The values about keys match and match_not are a list of {key, value}.

Response Parameters

Name

In

Type

Description

sessions (Optional)

body

list

A list of existing sessions.

Request Example

{
    "match_not": [
        {
            "schedule_interval": "10 days"
        }
    ],
    "match": [
        {
            "hold_off": 50
        }
    ]
}

Response Example

{
        "sessions":
        [
            {
                "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
                "description": "Instance Database backup ",
                "schedule":
                {
                    "schedule_interval": "1 days",
                    "status": "scheduled",
                    "event": "start"
                },
                "session_tag": 250,
                "session_id": "79eba555449d4cfe8ef66f34cb096295",
                "jobs":
                {
                    "0ae284d514eb47dd84154748b5056749":
                    {
                        "time_ended": 1493119342,
                        "status": "scheduled",
                        "result": "success",
                        "client_id": "752d8bd43d654e7a840bbfda77ce41af_szaher",
                        "time_started": 1493119341
                    }
                },
                "hold_off": 50
            }
        ]
}
POST
/v1/sessions

Creates session

Creates a session.

This operation creates a new session.

Normal response codes: 201

Error response codes:

  • Syntax Error (753)

  • BadRequest (400)

  • Unauthorized (401)

  • ServiceUnavailable (503)

Request Parameters

Name

In

Type

Description

description

body

string

A description of the session.

hold_off

body

int

Amount of time to wait before re-running the same session again.

session_tag

body

string

The event is being used to start or stop a session.

schedule

body

dict

A dictionary that holds the session secheduling information. It’s the same like job_schedule. it contains schedule_interval, status and event.

schedule_internval (Optional)

body

string

The scheduling information of the session. for examples “2 hours” it means the session will be executed every 2 hours.

event (Optional)

body

string

The event is being used to start or stop a session.

Request Example

{
   "session_tag":20,
   "description":"Webapp Database backup ",
   "hold_off":30,
   "schedule":{
      "schedule_interval":"1 hours",
      "status":"scheduled",
      "event":"start"
   }
}

Response Parameters

Name

In

Type

Description

session_id

body

string

The session UUID.

Response Example

{
        "session_id": "79eba555449d4cfe8ef66f34cb096295"
}
GET
/v1/sessions/{session_id}

Show sessions

Shows sessions.

This operation shows a certain session. It displays all session details with jobs included in this session.

Normal response codes: 200

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

session_id

query

string

The session UUID.

Response Parameters

Name

In

Type

Description

user_id

body

string

The user UUID.

description

body

string

A description of the session.

schedule

body

dict

A dictionary that holds the session secheduling information. It’s the same like job_schedule. it contains schedule_interval, status and event.

session_tag

body

string

The event is being used to start or stop a session.

session_id

body

string

The session UUID.

hold_off

body

int

Amount of time to wait before re-running the same session again.

Response Example

{
        "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
        "description": "Instance Database backup ",
        "schedule":
        {
            "schedule_interval": "1 days",
            "status": "scheduled",
            "event": "start"
        },
        "_version": 2,
        "session_tag": 250,
        "session_id": "79eba555449d4cfe8ef66f34cb096295",
        "hold_off": 50
}
{
        "user_id": "0cd44caf6db5486b94a04b33256a5ff4",
        "description": "Instance Database backup ",
        "schedule":
        {
            "schedule_interval": "1 days",
            "status": "scheduled",
            "event": "start"
        },
        "_version": 3,
        "session_tag": 250,
        "session_id": "79eba555449d4cfe8ef66f34cb096295",
        "jobs":
        {
            "0ae284d514eb47dd84154748b5056749":
            {
                "time_ended": 1493119342,
                "status": "scheduled",
                "result": "success",
                "client_id": "752d8bd43d654e7a840bbfda77ce41af_szaher",
                "time_started": 1493119341
            }
        },
        "hold_off": 50
}
PATCH
/v1/sessions

Updates a session

Updates a session.

This operation updates a new session.

Normal response codes: 200

Error response codes:

  • Syntax Error (753)

  • BadRequest (400)

  • Unauthorized (401)

  • ServiceUnavailable (503)

Request Parameters

Name

In

Type

Description

description

body

string

A description of the session.

hold_off

body

int

Amount of time to wait before re-running the same session again.

session_tag

body

string

The event is being used to start or stop a session.

schedule

body

dict

A dictionary that holds the session secheduling information. It’s the same like job_schedule. it contains schedule_interval, status and event.

schedule_internval (Optional)

body

string

The scheduling information of the session. for examples “2 hours” it means the session will be executed every 2 hours.

event (Optional)

body

string

The event is being used to start or stop a session.

session_id

query

string

The session UUID.

Request Example

{
  "session_tag": 250,
  "description": "Instance Database backup ",
  "hold_off": 50,
  "schedule": {
        "schedule_interval": "1 days",
        "status": "scheduled",
        "event": "start"
  }
}

Response Parameters

Name

In

Type

Description

session_id

body

string

The session UUID.

version

body

int

The document version.

Response Example

{
        "version": 5,
        "session_id": "0ec2c71697464d63813b419d2282a43a"
}
PUT
/v1/sessions/{session_id}/jobs/{job_id}

Add jobs

attaches job to a session.

This operation adds a certain job to a session. The api will load the job and the session and add the job to session document.

Normal response codes: 204

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

session_id

query

string

The session UUID.

job_id

query

string

The job UUID.

No response will be returned for this job.

DELETE
/v1/sessions/{session_id}/jobs/{job_id}

Remove jobs

Removes a job from a session.

This operation will remove a certain job to a session.

Normal response codes: 204

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

session_id

query

string

The session UUID.

job_id

query

string

The job UUID.

No response will be returned for this job.

POST
/v1/sessions/{session_id}/actions

Start sessions

Removes a job from a session.

This operation will remove a certain job to a session.

Normal response codes: 202

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

session_id

query

string

The session UUID.

Response Parameters

Name

In

Type

Description

result (Optional)

body

string

A string represents if the operation was successful success or failed.

session_tag

body

string

The event is being used to start or stop a session.

Response Example

{
  "result": "success",
  "session_tag": 21
}
DELETE
/v1/sessions/{session_id}

Remove sessions

Removes a session.

This operation will remove a certain a session.

Normal response codes: 204

Error response codes:

  • Unauthorized (401)

  • Forbidden (403)

Query Parameters

Name

In

Type

Description

session_id

query

string

The session UUID.

No response will be returned for this job.

Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

Backup and Disaster Recovery Service API Reference 7.2.0