Restore Endpoints

This section describes the usage and specifics of the available restore 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 Restores

This request lists all of the Service Instance's triggered restores.

Route

GET /v1/instances/:instance_id/restores

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

cURL

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

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 restore within the Service Instance
backup_id	integer	The internal ID of the backup within the Service Instance
status	string	The status of the task. The following statuses exist: queued, running, done, failed, deleted
metadata.restored_from	datetime	The creation date of the backup (or the selected point in time, in case of continuous archiving) used for the restore, in ISO 8601 UTC time
triggered_at	datetime	The date the task was triggered, 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

Example

[
  {
    "id": 2,
    "backup_id": 1,
    "metadata": {
      "restored_from": "2021-04-21T15:32:10.332Z"
    },
    "status": "done",
    "triggered_at": "2021-04-21T15:34:12.295Z",
    "finished_at": "2021-04-21T15:34:14.322Z"
  },
  {
    "id": 1,
    "backup_id": 1,
    "metadata": {
      "restored_from": "2021-04-21T15:32:10.332Z"
    },
    "status": "done",
    "triggered_at": "2021-04-21T15:31:19.910Z",
    "finished_at": "2021-04-21T15:31:31.337Z"
  }
]

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.

Get a Specific Restore

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

Route

GET /v1/instances/:instance_id/restores/:id

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

cURL

curl --insecure --header "Authorization: $(bearer_token)" \
  "${url}/restores/: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	integer	The internal ID of the backup within the Service Instance
status	string	The status of the task. The following statuses exist: queued, running, done, failed, deleted
metadata.restored_from	datetime	The creation date of the backup (or the selected point in time, in case of continuous archiving) used for the restore, in ISO 8601 UTC time
triggered_at	datetime	The date the task was triggered, 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

Example

{
  "id": 2,
  "backup_id": 1,
  "status": "done",
  "metadata": {
    "restored_from": "2021-04-21T15:32:10.332Z"
  },
  "triggered_at": "2021-04-21T15:34:12.295Z",
  "finished_at": "2021-04-21T15:34:44.308Z"
}

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.

Trigger a Restore

This request triggers the restoration process using the specified Service Instance's backup.

Route

POST /v1/instances/:instance_id/backups/:id/restore

:instance_id MUST be the ID of a previously provisioned Service Instance. :id MUST be the ID of an existing backup belonging to the Service Instance.

cURL

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

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
id	integer	The internal ID of the restore within the Service Instance

Example

{
  "id": 1
}

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.

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>