Version: Latest

Backups Endpoints

This section describes the usage and specifics of the available backup endpoints of the a9s Public API V1.

info

Before you can access any of the mentioned endpoints, you have to follow the steps mentioned in Accessing the a9s Public API.

List All Backups

This request lists all of the Service Service Instance's available backups.

Route

GET /v1/instances/:instance_id/backups

:instance_id MUST be the ID of a previously provisioned Service Instance.

cURL

curl --insecure --header "Authorization: $(bearer_token)" "${url}/backups"

Response

Body

For success responses, an array is returned. The objects are composed of the following fields:

Response Field	Type	Description
`id`	`integer`	The internal ID of the backup within the Service Instance.
`backup_id`	`string`	The ID of the backup within the Backup Manager and the storage itself. This can be used to Fork a Service Instance with a specific backup.
`size`	`integer`	The size of the backup, in bytes.
`status`	`string`	The status of the task. The following statuses exist: `queued`, `running`, `done`, `failed`, `deleted`.
`triggered_at`	`datetime`	The date the task was triggered, in ISO 8601 UTC time.
`started_at`	`datetime`	The date the task was picked up for processing, in ISO 8601 UTC time
`finished_at`	`datetime`	The date on which the status of the task was last changed, in ISO 8601 UTC time.
`downloadable`	`boolean`	Indicates if the backup can be downloaded via the a9s Service Dashboard.

Example

[
  {
    "id": 2,
    "backup_id": "8377f207-21b4-48fd-a75b-78c1bcdef8ca-1742693407644",
    "size": 2792,
    "status": "done",
    "triggered_at": "2021-04-21T01:30:03.832Z",
    "started_at": "2021-04-21T01:30:04.832Z",
    "finished_at": "2021-04-21T01:30:32.163Z",
    "downloadable": true
  },
  {
    "id": 1,
    "backup_id": "8377f207-21b4-48fd-a75b-78c1bcdef8ca-1742607006559",
    "size": 2792,
    "status": "done",
    "triggered_at": "2021-04-20T01:30:02.898Z",
    "started_at": "2021-04-20T01:30:04.898Z",
    "finished_at": "2021-04-20T01:30:31.883Z",
    "downloadable": false
  }
]

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`202` Accepted	The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`409` Conflict	There is already such action in progress.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Get a Specific Backup

This request returns the information of the specified Service Instance's backup.

Route

GET /v1/instances/:instance_id/backups/:id

:instance_id MUST be the ID of a previously provisioned Service Instance. :id MUST be the ID of the requested backup, within the Service Instance.

cURL

curl --insecure --header "Authorization: $(bearer_token)" "${url}/backups/:id"

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`id`	`integer`	The internal ID of the backup within the Service Instance
`backup_id`	`string`	The ID of the backup within the Backup Manager and the storage itself. This can be used to Fork a Service Instance with a specific backup.
`size`	`integer`	The size of the backup, in bytes.
`status`	`string`	The status of the task. The following statuses exist: `queued`, `running`, `done`, `failed`, `deleted`
`triggered_at`	`datetime`	The date the task was triggered, in ISO 8601 UTC time
`started_at`	`datetime`	The date the task was picked up for processing, in ISO 8601 UTC time
`finished_at`	`datetime`	The date on which the status of the task was last changed, in ISO 8601 UTC time
`downloadable`	`boolean`	Indicates if the backup can be downloaded via the a9s Service Dashboard

Example

  {
    "id": 1,
    "backup_id": "5e8a65aa-cac2-49db-8727-a9e9d70eafe3-1754875802631",
    "size": 2792,
    "status": "done",
    "triggered_at": "2021-04-20T01:30:02.898Z",
    "started_at": "2021-04-20T01:30:04.898Z",
    "finished_at": "2021-04-20T01:30:31.883Z",
    "downloadable": false
  }

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`202` Accepted	The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`409` Conflict	There is already such action in progress.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Create a Backup

This request triggers the creation of a new Service Instance's backup.

note

In order to be able to decrypt a downloaded backup, the encryption key must be known/set before triggering said backup. You can see how to do this here.

Route

POST /v1/instances/:instance_id/backups

:instance_id MUST be the ID of a previously provisioned Service Instance.

cURL

curl -X POST --insecure --header "Authorization: $(bearer_token)" \
  --header "Content-Type: application/json" "${url}/backups"

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`id`	`integer`	The internal ID of the backup within the Service Instance
`message`	`string`	The status of the task

Example

{
  "id": 1,
  "message": "job to backup is queued"
}

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`202` Accepted	The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`409` Conflict	There is already such action in progress.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Download a Backup

This request downloads the given backup of a given Service Instance.

Route

GET /v1/instances/:instance_id/backups/:id/download

:instance_id MUST be the ID of a previously provisioned Service Instance.
:id MUST be the ID of a previously performed backup.

cURL

curl --insecure --header "Authorization: $(bearer_token)" \
  "${url}/backups/:id/download" -o <backup_file_name>.tgz

Response

Status

Status Code	Description
`200` OK	If the backup download is started
`412` Precondition Failed	Either `instance_id` or `id` does not exist or match

Body

For success responses, the body contains the encrypted and compressed backup. The response should be piped into a file. In order to decrypt this file you must know/set the encryption key before triggering the backup. You can see how to do this here

How to decrypt and decompress the backup is described in this guide.

For error responses, the following fields are defined:

Response Field	Type	Description
`message`	`string`	A user-facing message that can be used to tell the user what went wrong
`status`	`int`	The status code of the error

note

There is a request timeout in the Cloud Foundry Gorouter component to handle external requests. By default, the timeout is configured for 15 minutes, therefore when a request reaches this timeout the request is aborted. To know more or request a change of the timeout, contact your Platform Operator.

Get Backups Configuration

This request gets the information regarding the Service Instance's backups configuration.

Route

GET /v1/instances/:instance_id/backups-config

:instance_id MUST be the ID of a previously provisioned Service Instance.

cURL

curl --insecure --header "Authorization: $(bearer_token)" \
  "${url}/backups-config"

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`min_backup_count`	`integer`	The minimum amount of backups per instance. When the amount of backups exceeds this number, the older backups will be deleted. The minimum value is 0
`retention_time`	`integer`	The retention time is measured in days and defines a time range after which backups are deleted. The minimum value is 0
`min_encryption_key_length`	`integer`	The minimum length of the backups' encryption key
`exclude_from_auto_backup`	`boolean`	States whether this instance will be excluded from scheduled backups. Default is false
`backup_type`	`string`	The backup type of a Service Instance. The following backup types exist: `standard`, `continuous_archiving`

Example

{
  "min_backup_count": 5,
  "retention_time": 5,
  "min_encryption_key_length": 8,
  "exclude_from_auto_backup": false,
  "backup_type": "standard"
}

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`202` Accepted	The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`409` Conflict	There is already such action in progress.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Update Backups Configuration

This request sets the information regarding the Service Instance's backups' configuration. This is currently limited to setting the backups' encryption key.

note

In order to be able to decrypt a downloaded backup, the encryption key MUST be known/set before triggering said backup.

Route

PATCH /v1/instances/:instance_id/backups-config

:instance_id MUST be the ID of a previously provisioned Service Instance.

Body

The body must be sent in valid JSON format.

Request Field	Type	Required	Description
`encryption_key`	`string`	false	The new backup encryption key. User provided value
`min_backup_count`	`integer`	false	The minimum amount of backups per instance. When the amount of backups exceeds this number, the older backups will be deleted. The minimum value is 0
`retention_time`	`integer`	false	The retention time is measured in days and defines a time range after which backups are deleted. The minimum value is 0
`exclude_from_auto_backup`	`boolean`	false	States whether this instance will be excluded from scheduled backups. Default is false

note

It is worth noting that while the a9s Backup Manager can change the encryption key, it does not return it, thus it is necessary to save it manually, in a secure place.

Keep in mind that setting a new encryption key will overwrite and replace any previously existing encryption key. This new encryption key is not retroactively applied, so any prior backups cannot be decrypted with it. Therefore, it is recommended that old encryption keys are kept in a secure place.

cURL

curl -X PATCH --insecure --header "Content-Type: application/json" --header "Authorization: $(bearer_token)" \
  --data '{"encryption_key":"<encryption_key>", "min_backup_count":<min_backup_count>, \
  "retention_time":<retention_time>, "exclude_from_auto_backup":<boolean-value> }' \
  "${url}/backups-config"

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`message`	`string`	A user-facing success message

Example

{
  "message": "instance updated"
}

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`422` Unprocessable Content	The provided parameters by the user are not valid
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

List All Backups​

Route​

cURL​

Response​

Body​

Status​

Get a Specific Backup​

Route​

cURL​

Response​

Body​

Status​

Create a Backup​

Route​

cURL​

Response​

Body​

Status​

Download a Backup​

Route​

cURL​

Response​

Status​

Body​

Get Backups Configuration​

Route​

cURL​

Response​

Body​

Status​

Update Backups Configuration​

Route​

Body​

cURL​

Response​

Body​

Status​

List All Backups

Route

cURL

Response

Body

Status

Get a Specific Backup

Route

cURL

Response

Body

Status

Create a Backup

Route

cURL

Response

Body

Status

Download a Backup

Route

cURL

Response

Status

Body

Get Backups Configuration

Route

cURL

Response

Body

Status

Update Backups Configuration

Route

Body

cURL

Response

Body

Status