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 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.

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 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.

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.