API V0 Endpoints
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 Code | Description |
---|---|
200 OK | If the request has been processed successfully. The response body is below. |
Body
For success responses, the following fields are defined:
Response Field | Type | Description |
---|---|---|
id | integer | The internal ID of the Service Instance. |
instance_id | string | The ID of the Service Instance as defined in the a9s Service Broker or Cloud Foundry. |
backups | array of Backup objects | Schema of backup objects defined below. May be empty. |
restores | array of Restore objects | Schema of restore objects defined below. May be empty. |
Backup Object
Response Field | Type | Description |
---|---|---|
id | integer | The internal ID of the backup. |
instance_id | integer | The internal ID of the related Service Instance. |
backup_agent_task | A Backup Agent Task object | Schema of backup agent task objects defined below. |
Restore Object
Response Field | Type | Description |
---|---|---|
id | integer | The internal ID of the restore. |
instance_id | integer | The internal ID of the related Service Instance. |
backup_agent_tasks | array of Backup Agent Task objects | Schema of backup agent task objects defined below. |
Backup Agent Task Object
Response Field | Type | Description |
---|---|---|
id | integer | The internal ID of the task. |
task_id | integer | The internal ID of the related backup/restore. |
status | string | The status of the task. The following statuses exist: queued , running , done , failed , deleted . |
created_at | datetime | The date the backup task was created (queued). |
updated_at | datetime | The 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 Code | Description |
---|---|
201 Created | If the backup has been scheduled. |
Body
For success responses, the following fields are defined:
Response Field | Type | Description |
---|---|---|
id | integer | The ID of the backup. |
message | string | A 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 -X POST --cookie session.cookie --cookie-jar session.cookie \
--location --insecure --header "Authorization: ${bearer_token}" \
--header "Content-Type: application/json" "${url}/backups/restore" \
--data '{"backup_id":"<backup_id>", "instance_id":"<instance_id>"}'
Body
Request Field | Type | Description |
---|---|---|
instance_id | integer | The internal ID of the Service Instance. |
backup_id | integer | The internal ID of the backup. |
Response
Status
Status Code | Description |
---|---|
200 OK | If the restore has been scheduled. |
412 Precondition Failed | Either instance_id or backup_id does not exist or match. |
Body
For success responses, the following fields are defined:
Response Field | Type | Description |
---|---|---|
restore_id | integer | The internal ID of the restore. |
For error responses, the following fields are defined:
Response Field | Type | Description |
---|---|---|
msg | string | A user-facing message that can be used to tell the user what went wrong. |
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 Code | Description |
---|---|
200 OK | If the backup download is started |
412 Precondition Failed | Either 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 Field | Type | Description |
---|---|---|
msg | string | A user-facing message that can be used to tell the user what went wrong. |
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.