Skip to main content
Version: 46.0.0

API V0 Endpoints

Deprecation Notice

This version of the a9s Public API is now deprecated, and will be discontinued in future releases, please consider using the new version of the a9s Public API V1

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

This topic describes how to use the a9s Public API, in order to enable and disable features in the frontend, get information about the service instance or start or restore backups.

List Backups and Restores

This request lists all available backups, as well as the restores that have been applied.

Route

GET /service-instances/:instance_id/backups

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

cURL

curl --cookie session.cookie --cookie-jar session.cookie \
--location --insecure --header "Authorization: ${bearer_token}" "${url}/backups"

Response

Status

Status CodeDescription
200 OKIf the request has been processed successfully. The response body is below.

Body

For success responses, the following fields are defined:

Response FieldTypeDescription
idintegerThe internal ID of the Service Instance.
instance_idstringThe ID of the Service Instance as defined in the a9s Service Broker or Cloud Foundry.
backupsarray of Backup objectsSchema of backup objects defined below. May be empty.
restoresarray of Restore objectsSchema of restore objects defined below. May be empty.
Backup Object
Response FieldTypeDescription
idintegerThe internal ID of the backup.
instance_idintegerThe internal ID of the related Service Instance.
backup_agent_taskA Backup Agent Task objectSchema of backup agent task objects defined below.
Restore Object
Response FieldTypeDescription
idintegerThe internal ID of the restore.
instance_idintegerThe internal ID of the related Service Instance.
backup_agent_tasksarray of Backup Agent Task objectsSchema of backup agent task objects defined below.
Backup Agent Task Object
Response FieldTypeDescription
idintegerThe internal ID of the task.
task_idintegerThe internal ID of the related backup/restore.
statusstringThe status of the task. The following statuses exist: queued, running, done, failed, deleted.
created_atdatetimeThe date the backup task was created (queued).
updated_atdatetimeThe date on which the status of the task was last changed.
{
"id": 85,
"instance_id": "db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d",
"backups": [
{
"id": 2811,
"instance_id": 85,
"backup_agent_task": {
"id": 2901,
"task_id": 2811,
"status": "done",
"created_at": "2017-06-29T00:30:03.857Z",
"updated_at": "2017-06-29T00:30:18.091Z"
}
}
],
"restores": [
{
"id": 84,
"instance_id": 85,
"backup_agent_tasks": [
{
"id": 843,
"task_id": 84,
"status": "done",
"created_at": "2017-06-20T14:51:08.661Z",
"updated_at": "2017-06-20T14:51:19.856Z"
}
]
}
]
}

Create Backup

This request triggers the backup process on a given Service Instance.

Route

POST /service-instances/:instance_id/backups

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

cURL

curl --cookie session.cookie --cookie-jar session.cookie \
--location --insecure --header "Authorization: ${bearer_token}" \
--header "Content-Type: application/json" -X POST "${url}/backups"

Response

Status

Status CodeDescription
201 CreatedIf the backup has been scheduled.

Body

For success responses, the following fields are defined:

Response FieldTypeDescription
idintegerThe ID of the backup.
messagestringA user-facing message that can be used to tell the user that the backup has been scheduled.

Restore Backup

This request restores a backup to a given Service Instance.

Route

POST /service-instances/:instance_id/backups/restore

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

cURL

curl --cookie session.cookie --cookie-jar session.cookie \
--location --insecure --header "Authorization: ${bearer_token}" \
-X POST "${url}/backups/restore" --data "instance_id=<instance_id>" \
--header "Content-Type: application/json" --data "backup_id=<backup_id>"

Body

Request FieldTypeDescription
instance_idintegerThe internal ID of the Service Instance.
backup_idintegerThe internal ID of the backup.

Response

Status

Status CodeDescription
200 OKIf the restore has been scheduled.
412 Precondition FailedEither instance_id or backup_id does not exist or match.

Body

For success responses, the following fields are defined:

Response FieldTypeDescription
restore_idintegerThe internal ID of the restore.

For error responses, the following fields are defined:

Response FieldTypeDescription
msgstringA user-facing message that can be used to tell the user what went wrong.
Rebinding Application after Restoring a Backup

While restoring a backup is usually a straightforward task, it should be noted that after restoring a backup to an a9s Data Service instance, you are required to both rebind your application to your a9s Data Service instance, and to immediately restage it.

Taking Cloud Foundry as an example, this means that after restoring the backup, you should execute the following commands:

$ cf unbind-service <my_app> <my_service_instance>  
$ cf bind-service <my_app> my_service_instance
$ cf restage <my_app>

Download Backup

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

Route

POST /service-instances/:instance_id/backups/:backup_id/download

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

cURL

curl --cookie session.cookie --cookie-jar session.cookie --location --insecure \
--header "Authorization: ${bearer_token}" --header "Content-Type: application/json" \
"${url}/backups/<backup_id>/download" > <backup_file_name>.tgz

Response

Status

Status CodeDescription
200 OKIf the backup download is started
412 Precondition FailedEither instance_id or backup_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. The steps to decrypt and decompress the backup are described in this guide

For error responses, the following fields are defined:

Response FieldTypeDescription
msgstringA user-facing message that can be used to tell the user what went wrong.
info

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 to request a change of the timeout, contact your Platform Operator.