Version: Develop

a9s Service Dashboard

This topic describes how to use the a9s Service Dashboard.

To get the a9s Service Dashboard URL use the command cf service SERVICE-NAME. For example:

$ cf service my-redis
Showing info of service my-redis in org demo / space demo as admin...

name:            my-redis
service:         a9s-redis32
tags:
plan:            redis-single-small
description:     This is a service creating and managing dedicated Redis service instances, powered by the anynines Service Framework
documentation:
dashboard:       https://a9s-redis-dashboard.system.172.28.32.25.xip.io/service-instances/96aaef1d-be67-45fc-a121-25160bf83ab2

This service is not currently shared.

Showing status of last operation from service my-redis...

status:    create succeeded
message:
started:   2018-10-17T11:25:04Z
updated:   2018-10-17T11:29:10Z

There are no bound apps for this service.

Browse to the dashboard URL and authenticate on the redirected page with your Cloud Foundry credentials:

Click Authorize to approve the authorization request:

Perform a Backup

Open the Service Dashboard for the Service Instance you want to backup, as shown above. Navigate to the Backups page. There you find a panel with Available Backups and a Settings Icon which opens a submenu where you can find a Manually Trigger A Backup button. Click this button to perform a new backup of the Service Instance.

After a short period of time the backup will be queued. The backup process will start soon.

NOTE: Depending on the size of the data the backup will take some time.

NOTE: The backup time displayed is calculated from the moment the backup is queued until its resolution. Meaning the time spent in the queue is currently also part of this amount.

Restore a Backup

Open the Service Dashboard for the Service Instance, as shown above, you want to restore a backup that you performed before. Navigate to the Backups page. There you find a panel with Available Backups and a Restore button next to each backup. Click this button to trigger a restore.

A dialog opens and ask for confirmation. Press the YES button to continue or the No button to abort the restore.

After a short period of time the restore will be queued. The restore process will start soon.

NOTE: Depending on the size of the data the restore will take some time.

Restore History

When a restore is triggered, it is logged and listed as shown below:

When using a single instance, it is listed as a single entry per restore, as seen before.

In the case of a cluster however, the way that the restores are listed will vary depending on the service in use. This variation can be divided into two groups: master only restore and multi-node restore.

Take for example our a9s-MongoDB service, it does a restore on every node, so these are sequentially generated restores that will appear as multiple restores, but with a fused Backup created at row, as shown below:

On the other hand, the a9s-PostgreSQL service will only execute the restore on the master node. Therefore only one row is listed, like with the single instance example.

See the following list for further details:

Component	Restore-Type
a9s-Elasticsearch	master-only
a9s-MariaDB	master-only
a9s-PostgreSQL	master-only
a9s-Messaging	master-only
a9s-Redis	multi-node
a9s-MongoDB	multi-node

Download a Backup

To be able to download a performed backup you have to set a personal encryption key first. Otherwise a performed backup is not downloadable.

To set a personal encryption key, open the Service Dashboard for the appropriate Service Instance as shown above. Navigate to the Backups page and open the Settings menu by clicking the Settings icon on that panel. Afterwards click on the Set Encryption Key button.

Enter your personal encryption key in the field Encryption Key and click the Save button. The default minimum length for your personal encryption key is 8 characters.

After that, perform a backup as shown above. If the backup is successfully finished the button Download beside the backup becomes clickable. Click this button to download the corresponding backup.

NOTE:

If you change your personal encryption key again, you are not longer able to download performed backups, encrypted with your old personal encryption key.
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.

Automatic Reload

To reload the information shown, click on the Reload icon in the upper right corner of the dashboard. To enable Automatic Reload of the dashboard information, just enable the Switch button next to the Reload icon.

Update the Service Instance

To update a service instance, open the Updates page using the navbar on the top of the dashboard application. Afterwards you will see if there are any updates available for the selected instance.

Restart or Recreate the Service Instance

To Restart or Recrate a running service instance you are able to use the related buttons in the lower left corner of the dashboard application.

NOTE: The restart button will trigger a shutdown/turn-on actions on all processes of the current instance. The recreate button will remove and recreate the current instance and its related processes.

Instance Metrics

The Service Dashboard also offers a visualization of the following metrics from your Service Instance, per node:

Average system load (CPU)
Disk usage
RAM usage

This allows you to know at a glance your current consumption of resources.

For a single instance, the metrics are displayed as shown in the image below:

For a cluster instance, the metrics are displayed in separate tabs, one per node, as shown in the image below:

NOTE: The order of the tabs is dynamic, meaning there is no special order in which they are displayed.

Size Calculation

The metrics collector gathers and shares the Service Instance's metrics in bytes, but these values are too large to be displayed in a humanly readable way. Therefore, the values are converted to megabytes, and we took the decision to divide this by 1024^2. Thus, the value printed by the dashboard might sometimes differ from other tools that take the approach of dividing by 1000^2.

The data is then displayed in a used/available format.

Disks

The a9s Service Dashboard only displays the following disks:

system: contains the operating system itself
ephemeral: mainly used for automation/infrastructure data and log data
persistent: mainly used for persistent data of the underlying data service

While the metrics of other disks are gathered and shared by the metrics collector they are ignored by the a9s Service Dashboard. This design decision was taken in order to avoid overflowing the dashboard's metrics visualization with temporary disks.

API

Deprecation Notice

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

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

How to access the API using cURL

We run the a9s Service Dashboard API protected by the a9s SSO Proxy. This means that in order to access this API, we need to be authenticated and authorized first, to access it.

Authentication

To correctly authorize the request when accessing using cURL, the user must first get the token from Cloud Foundry:

bearer_token=$(cf oauth-token | grep bearer)

Then, get the a9s Service Dashboard URL using cf service:

$ cf service <service_name>

This should give you an output like:

Showing info of service my-service in org example / space example as admin...

name:            my-service
service:         a9s-redis
[...]
dashboard:       https://a9s-redis-dashboard.example.com/service-instances/db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d

Showing status of last operation from service my-service...

status:    create succeeded
[...]

In the example above, the URL is:

url="https://a9s-redis-dashboard.example.com/service-instances/db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d"

Authorization

The user must execute the following command with the given Cloud Foundry token and a9s Service Dashboard URL, and then it creates the cookie authorized to be used in future API requests.

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

Remember to use --location, since the a9s SSO Proxy redirects to the real endpoint.
Use --insecure only, if running the service instance with self generated certificates.
Use --cookie-jar to store the authorized cookie in a file to be used in future API requests.

The authentication is handled by Cloud Foundry, so when you have a valid token, you are authenticated. With this token, the a9s SSO Proxy checks if you are authorized to access the a9s Service Dashboard for the given instance.

Once the user is authorized, this information is stored in the session, which is then stored in the cookie. After this, the requests can be redirected to the a9s Service Dashboard API and the user can access all the provided endpoints as described below.

Note: This authorization step must be done before the API request when the user is not authorized yet.

Headers

The following HTTP Headers are defined for the operations on this API:

Header	Type	Description
Authorization*	`string`	A token that is authorized to access the a9s Service Dashboard API for the given Service Instance.

* Headers with an asterisk are required.

List Backups and Restores

Lists all available backups as well as the restores that have been applied.

Request

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

Start a backup process on a given Service Instance.

Request

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

Restores a backup to a given Service Instance.

Request

Route

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

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

Body

Request Field	Type	Description
`instance_id`	`integer`	The internal ID of the Service Instance.
`backup_id`	`integer`	The internal ID of the backup.

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

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.

Download Backup

Downloads the given backup of a given Service Instance

Request

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. How to decrypt and decompress the backup is 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.

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.

API V1

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

The available endpoints are sorted into the groups listed below, to facilitate the navigation of this document:

Backups
Instances
Metrics

How to access the API using cURL

We run the a9s Service Dashboard API protected by the a9s SSO Proxy. This means that in order to access this API, we need to be authenticated and authorized first, to access it.

Authentication

To correctly authorise the request when accessing using cURL, the user must first get the token from Cloud Foundry:

bearer_token=$(cf oauth-token | grep bearer)

Then, get the a9s Service Dashboard URL using cf service:

$ cf service <service_name>

This should give you an output like:

Showing info of service my-service in org example / space example as admin...

name:            my-service
service:         a9s-redis
[...]
dashboard:       https://a9s-redis-dashboard.example.com/service-instances/db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d

Showing status of last operation from service my-service...

status:    create succeeded
[...]

From this example we need to replace the current basepath /service-instances with the following basepath /v1/instances; while the scheme, host, and service instance id remain the same.

In the example above, the URL we construct ends up looking like this:

url="https://a9s-redis-dashboard.example.com/v1/instances/db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d"

Authorization

The user must execute the request with the given token:

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

Remember to use --location, since the a9s SSO Proxy redirects to the real endpoint.
Use --insecure only, if running the service instance with self generated certificates.

You should also use cookies. The authentication is handled by Cloud Foundry, so when you have a valid token, you are authenticated. With this token, the a9s SSO Proxy checks if you are authorized to access the a9s Service Dashboard for the given instance.

Once the user is authorised, this information is stored in the session, which is then stored in the cookie. After this, the requests can be redirected to the a9s Service Dashboard API and the user can access all the provided endpoints as described below.

Headers

The following HTTP Headers are defined for the operations on this API:

Header	Type	Description
Authorization*	`string`	A token that is authorized to access the a9s Service Dashboard API for the given Service Instance

* Headers with an asterisk are required.

Backups

The API V1 has the following backup related endpoints available:

List all backups
Get a specific backup
Create a backup
Download a Backup
List all restores
Get a specific restore
Trigger a restore
Get Backups configuration
Update Backups configuration

List All Backups

Lists all of the instance's available backups.

Request

Route

GET /v1/instances/:instance_id/backups

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

cURL

curl --cookie test.cookie --cookie-jar test.cookie \
  --location --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
`size`	`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`
`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
`downloadable`	`boolean`	Indicates if the backup can be downloaded via the a9s Service Dashboard

Example:

[
  {
    "id": 2,
    "size": 2792,
    "status": "done",
    "triggered_at": "2021-04-21T01:30:03.832Z",
    "finished_at": "2021-04-21T01:30:32.163Z",
    "downloadable": true
  },
  {
    "id": 1,
    "size": 2792,
    "status": "done",
    "triggered_at": "2021-04-20T01:30:02.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
`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
`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

Returns the information of the specified instance's backup.

Request

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 --cookie test.cookie --cookie-jar test.cookie \
  --location --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
`size`	`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`
`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
`downloadable`	`boolean`	Indicates if the backup can be downloaded via the a9s Service Dashboard

Example:

  {
    "id": 1,
    "size": 2792,
    "status": "done",
    "triggered_at": "2021-04-20T01:30:02.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
`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
`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

Triggers the creation of a new 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

Request

Route

POST /v1/instances/:instance_id/backups

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

cURL

curl -X POST --cookie test.cookie --cookie-jar test.cookie  --location --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
`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
`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

Downloads the given backup of a given Service Instance.

Request

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 --cookie test.cookie --cookie-jar test.cookie \
  --location --insecure --header "Authorization: ${bearer_token}" \
  "${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 `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

List All Restores

Lists all of the instance's triggered restores.

Request

Route

GET /v1/instances/:instance_id/restores

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

cURL

curl --cookie test.cookie --cookie-jar test.cookie \
  --location --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`
`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",
    "triggered_at": "2021-04-21T15:34:12.295Z",
    "finished_at": "2021-04-21T15:34:14.322Z"
  },
  {
    "id": 1,
    "backup_id": 1,
    "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

Returns the information of the specified instance's restore.

Request

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 --cookie test.cookie --cookie-jar test.cookie \
  --location --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
`size`	`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`
`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

{
  "id": 2,
  "backup_id": 1,
  "status": "done",
  "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
`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
`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

Triggers the restoration process using the specified instance's backup.

Request

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 --cookie test.cookie --cookie-jar test.cookie --location --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
`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
`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 Backups Configuration

Gets the information regarding the instance's backups configuration.

Request

Route

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

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

cURL

curl --cookie test.cookie --cookie-jar test.cookie \
  --location --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 the 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
`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
`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

Sets the information regarding the 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.

Request

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

cURL

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

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

Disaster Recovery

The API V1 has the following disaster recovery related endpoints available:

Prepare a Disaster Recovery
Perform a Diaster Recovery

Prepare a Disaster Recovery

Prepares the required information for an instance's disaster recovery.

Request

Route

POST /v1/instances/:instance_id/disaster-recovery/prepare

Body

The body must be sent in valid JSON format.

Request Field	Type	Required	Description
`encryption_key`	`string`	false	Optional The key which the Backup Manager is using to encrypt backups

cURL

curl -X POST --cookie test.cookie --cookie-jar test.cookie --location \
  --header "Content-Type: application/json" --header "Authorization: ${bearer_token}" \
  "${url}/disaster-recovery/prepare" --data '{"encryption_key":"<encryption_key>"}'

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`backup_guid`	`string`	The GUID which the a9s Backup Manager is using to refer to backups of a given instance

Example:

{
  "backup_guid": "3a2e59ee-40cb-472a-91d0-502ab259918c"
}

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

Perform a Disaster Recovery

Performs an instance's disaster recovery in the destination service instance.

Request

Route

POST /v1/instances/:instance_id/disaster-recovery/perform

Body

The body must be sent in valid JSON format.

Request Field	Type	Required	Description
`backup_guid`	`string`	true	The GUID which the a9s Backup Manager uses to refer to the originating service instance's backups
`encryption_key`	`string`	true	The key which the Backup Manager is using to encrypt backups

cURL

curl -X POST --cookie test.cookie --cookie-jar test.cookie --location \
  --header "Content-Type: application/json" --header "Authorization: ${bearer_token}" \
  "${url}/disaster-recovery/perform" --data '{"encryption_key":"<encryption_key>", "backup_guid":"<backup_guid>"}'

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`restore_id`	`integer`	The internal ID of the restore in the destination service instance.

Example:

{
  "restore_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
`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
`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

Instances

The API V1 has the following service instance related endpoints available:

Get instance overview
Trigger a recreate
Trigger a restart
Trigger an update

Get Instance Overview

Gets the instance's overview information.

Request

Route

GET /v1/instances/:instance_id

cURL

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

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`available_updates`	`array` of available updates objects	Schema of available updates objects defined below
`created_at`	`datetime`	The date the instance was created, in ISO 8601 UTC time
`id`	`int`	The id of the instance within the Data Service
`name`	`string`	The given name of the instance
`plan_id`	`string`	The id of the plan the instance was created under
`service_id`	`string`	The id of the Data Service from which the instance was created
`state`	`string`	Current state of the instance. The following states exist: `provisioned`, `available`, `deleted`, `deploying`, `failed`
`subtenant_id`	`string`	The id of the subtenant (e.g. space in CF)
`subtenant_name`	`string`	The name of the subtenant (e.g. space in CF)
`tenant_id`	`string`	The id of the tenant (e.g. organization in CF)
`tenant_name`	`string`	The name of the subtenant (e.g. space in CF)
`updated_at`	`datetime`	The date when the instance was last updated, in ISO 8601 UTC time
`urls`	`array` of URLs objects	Schema of URLs objects defined below

Available Updates Object

Response Field	Type	Description
`name`	`string`	The name of the component with available updates
`type`	`string`	The type of update of the component
`version`	`string`	The version of the available update

URLs Object

Response Field	Type	Description
`display_name`	`string`	The display name of the URL
`id`	`string`	The ID of the URL
`link`	`string`	The full URL string

Example:

{
  "available_updates": [
    {
      "name": "redis6",
      "type": "release",
      "version": "1.6.2"
    }
  ],
  "created_at": "2021-04-19T18:32:55.970Z",
  "id": 1,
  "name": "my-service",
  "plan_id": "77f163d4-0879-482d-bc93-085143bce70e",
  "service_guid": "855887d9-9096-4ddf-a40f-89e6f72da2d1",
  "service_id": "855887d9-9096-4ddf-a40f-89e6f72da2d1",
  "state": "provisioned",
  "subtenant_id": "fffd9f2a-45c6-4368-8d7a-afab38c0e594",
  "subtenant_name": "manual",
  "tenant_id": "68470a75-fd07-4897-b868-16e81fab46a5",
  "tenant_name": "system",
  "updated_at": "2021-04-22T01:30:06.165Z",
  "urls": [
    {
      "display_name": "Redis",
      "id": "Redis-link",
      "link": "https://a9s-redis-dashboard.example.com/service-instances/db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d/redis"
    },
    {
      "display_name": "Service Instance Dashboard",
      "id": "Dashboard",
      "link": " https://a9s-redis-dashboard.example.com/service-instances/db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d"
    }
  ]
}

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
`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 Recreate

Request

Triggers the recreate process of the instance.

Route

PATCH /v1/instances/:instance_id/recreate

cURL

curl -X PATCH --cookie test.cookie --cookie-jar test.cookie \
  --location --insecure --header "Authorization: ${bearer_token}" \
  --header "Content-Type: application/json" "${url}/recreate"

Response

Body

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
`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
`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 Restart

Request

Triggers the restart process of the instance.

Route

PATCH /v1/instances/:instance_id/restart

cURL

curl -X PATCH --cookie test.cookie --cookie-jar test.cookie \
  --location --insecure --header "Authorization: ${bearer_token}" \
  --header "Content-Type: application/json" "${url}/restart"

Response

Body

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
`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
`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 an Update

Request

Triggers the update process of for all available updates of the current the instance.

Route

PATCH /v1/instances/:instance_id/updates

Body

The body must be sent in valid JSON format.

Response Field	Type	Description
`service_id`	`string`	The id of the Service from which the instance was spawned from

cURL

curl -X PATCH --cookie test.cookie --cookie-jar test.cookie \
  --location --insecure --header "Authorization: ${bearer_token}" \
  --header "Content-Type: application/json" "${url}/updates" \
  --data '{"service_id":"<service_id>"}'

Response

Body

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

Metrics

Displays the metrics of your Service Instance.

Request

Route

GET /v1/instances/:instance_id/metrics?quantity=x

:instance_id MUST be the ID of a previously provisioned Service Instance.
quantity Number of latest elements to be returned. If not set, all elements WILL be returned. If set, quantity MUST be greater than or equal to 1.

cURL

curl --cookie session.cookie --cookie-jar session.cookie \
  --location --insecure --header "Authorization: ${bearer_token}" \
  "${url}/metrics?quantity=1"

Response

The response is a JSON that contains a collection of metrics DataPoints. These DataPoints are strings in Graphite format: <path> <value> <timestamp>.

path: The metric namespace. The string is made of 3 independent parts separated by dots (.): <namespace>.<type>.<specific>
- namespace: The component under observation. For example:
  - 38d0cd8e21a-d9be-48ef-bfcd-dbaa4298c946.60aed25d-212d-4689-b9f6-74319de1d6a7.d1d51e37-9a26-4242-9909-79cc4b519c16.7c2cb2684.pg.0
  - 38d0cd8e21a-d9be-48ef-bfcd-dbaa4298c946.60aed25d-212d-4689-b9f6-74319de1d6a7.c601850d-7fd9-4034-84db-5ce9190a9c2b.10249a7b4.redis.2
  As shown by the example, you can note that namespace are composed of <organization_id>.<space_id>.<instance_id>.<deployment_name>.<service_type>.<node_id>. But this might not always be the case. While <instance_id>, <deployment_name>, <service_type> and <node_id> are fix and you can not change it; <organization_id> and <space_id> must be enabled by the operator.
- type: The DataPoint type that is looked after. See types
- specific: The kind of data point that is looked after. See specifics
value: The number that is assigned to the metric at this time
timestamp: The number of seconds elapsed since the Unix epoch

DataPoint Types

Currently the suported DataPoint type is system.

system DataPoint Specifics

The following are the supported specifics for the system DataPoint type.

Load

Name	Description
load.error	0 if the load average metrics could be fetched, 1 otherwise
load.load1	represents the average system load during the last one-minute period of time; multiplied by 1000000
load.load5	represents the average system load during the last five-minute period of time; multiplied by 1000000
load.load15	represents the average system load during the last fifteen-minute period of time; multiplied by 1000000

CPUs

The CPU number starts at 0.

Name	Description
cpu.error	0 if the CPU stats could be fetched, 1 otherwise
cpu\<number>.user	the amount of time in milliseconds the CPU was busy running non-kernel code (user time, including nice time)
cpu\<number>.system	the amount of time in milliseconds the CPU was busy running kernel code
cpu\<number>.idle	the amount of time in milliseconds the CPU was not busy, or, otherwise, the amount of time in milliseconds it executed the kernel idle handler

Memory

Name	Description
memory.error	0 if the memory stats could be fetched, 1 otherwise
memory.total	the maximum available amount of memory in bytes
memory.used	the amount of memory in bytes currently being used. It is calculated by the following formula: `Memory Total - (Memory free + Memory Cache + Memory Buffer + Memory SReclaimable)`
memory.free	the amount of memory in bytes not currently in use by any running process
memory.shared	the amount of memory in bytes used by the tmpfs file system and also the shared memory
memory.buffers	the amount of memory in bytes used as buffers
memory.cached	the amount of memory in bytes used as cache

Note: Linux (like most modern operating systems) will always try to use free memory for caching purposes. Therefore, the free memory will almost always be very small. Since caches are automatically freed when memory becomes scarce, they must be considered accordingly to see how much memory is really available.

Swap

Name	Description
swap.error	0 if the swap stats could be fetched, 1 otherwise
swap.total	the maximum available amount of swap space in bytes
swap.used	the amount of swap space in bytes currently being used
swap.free	the amount of swap space in bytes not currently in use by any running process

Disks

Only physical devices with a size greater than 0 are monitored.

Name	Description
disk.error	0 if the available disks stats could be fetched, 1 otherwise
disk.\<name>.error	0 if the disk stats could be fetched, 1 otherwise
disk.\<name>.total	the maximum available amount of disk space in bytes
disk.\<name>.used	the amount of disk space in bytes currently being used
disk.\<name>.free	the amount of disk space in bytes not currently in use. Does not include the space reserved for the root user (5%)

The mount point of the device is used as name. The first / of the mount point is removed and all other / are replaced by _. The following mount points have special names:

Mount Point	Name
`/`	system
`/var/vcap/data`	ephemeral
`/var/vcap/store`	persistent

parachute DataPoint Specifics

The following are the supported specifics for the parachute DataPoint type.

General

Name	Description
error	0 if the a9s Parachute stats could be fetched, 1 otherwise
activated	1 if the a9s Parachute is activated because at least one disk has reached the configured threshold, 0 otherwise

Disks

Only the observed devices of the a9s Parachute are monitored.

Name	Description
disk.\<name>.error	0 if the disk stats could be fetched, 1 otherwise
disk.\<name>.total	the maximum available amount of disk space in bytes
disk.\<name>.used	the amount of disk space in bytes currently being used
disk.\<name>.used_percent	the amount of disk space in percent currently being used
disk.\<name>.used_threshold	the threshold value in percent of disk space at which the a9s Parachute is activated
disk.\<name>.free	the amount of disk space in bytes not currently in use. Does not include the space reserved for the root user (5%)
disk.\<name>.activated	1 if the a9s Parachute is activated because this disk has reached the configured threshold, 0 otherwise

Body

For success responses, the body contains the collection of metrics DataPoints which can be piped to a file.

[
  "redis.0.system.cpu.error 0 1594380720",
  "redis.0.system.cpu0.user 894310 1594380720",
  "redis.0.system.cpu0.system 410430 1594380720",
  "redis.0.system.cpu0.idle 72292610 1594380720",
  "redis.0.system.load.load1 3542480 1594380720",
  "redis.0.system.load.load5 3152832 15943807720",
  "redis.0.system.load.load15 2358398 15943807720",
  "redis.0.system.memory.error 0 1594380720",
  "redis.0.system.memory.total 4136923136 1594380720",
  "redis.0.system.memory.used 3278594048 1594380720",
  "redis.0.system.memory.free 151093248 1594380720",
  "redis.0.system.memory.shared 21757952 1594380720",
  "redis.0.system.memory.buffers 137117696 1594380720",
  "redis.0.system.memory.cached 570118144 1594380720",
  "redis.0.system.swap.error 0 1594380720",
  "redis.0.system.swap.total 4136628224 1594380720",
  "redis.0.system.swap.used 0 1594380720",
  "redis.0.system.swap.free 4136628224 1594380720",
  "redis.0.system.disk.error 0 1594380720",
  "redis.0.system.disk.system.error 0 1594380720",
  "redis.0.system.disk.system.total 3103686656 1594380720",
  "redis.0.system.disk.system.used 1558130688 1594380720",
  "redis.0.system.disk.system.free 1369866240 1594380720",
  "redis.0.system.disk.ephemeral.error 0 1594380720",
  "redis.0.system.disk.ephemeral.total 6113067008 1594380720",
  "redis.0.system.disk.ephemeral.used 1042546688 1594380720",
  "redis.0.system.disk.ephemeral.free 4736393216 1594380720",
  "redis.0.system.disk.var_log.error 0 1594380720",
  "redis.0.system.disk.var_log.total 6113067008 1594380720",
  "redis.0.system.disk.var_log.used 1042546688 1594380720",
  "redis.0.system.disk.var_log.free 4736393216 1594380720",
  "redis.0.system.disk.tmp.error 0 1594380720",
  "redis.0.system.disk.tmp.total 6113067008 1594380720",
  "redis.0.system.disk.tmp.used 1042546688 1594380720",
  "redis.0.system.disk.tmp.free 4736393216 1594380720",
  "redis.0.system.disk.var_tmp.error 0 1594380720",
  "redis.0.system.disk.var_tmp.total 6113067008 1594380720",
  "redis.0.system.disk.var_tmp.used 1042546688 1594380720",
  "redis.0.system.disk.var_tmp.free 4736393216 1594380720",
  "redis.0.system.disk.home.error 0 1594380720",
  "redis.0.system.disk.home.total 3103686656 1594380720",
  "redis.0.system.disk.home.used 1558130688 1594380720",
  "redis.0.system.disk.home.free 1369866240 1594380720",
  "redis.0.system.disk.persistent.error 0 1594380720",
  "redis.0.system.disk.persistent.total 5148114944 1594380720",
  "redis.0.system.disk.persistent.used 10547200 1594380720",
  "redis.0.system.disk.persistent.free 4852461568 1594380720"
  "redis.0.parachute.error 0 1594380720",
  "redis.0.parachute.activated 1 1594380720",
  "redis.0.parachute.disk.ephemeral.error 0 1594380720",
  "redis.0.parachute.disk.ephemeral.total 6113067008 1594380720",
  "redis.0.parachute.disk.ephemeral.used 1068199936 1594380720",
  "redis.0.parachute.disk.ephemeral.used_percent 18 1594380720",
  "redis.0.parachute.disk.ephemeral.used_threshold 10 1594380720",
  "redis.0.parachute.disk.ephemeral.free 4710739968 1594380720",
  "redis.0.parachute.disk.ephemeral.activated 1 1594380720",
  "redis.0.parachute.disk.persistent.error 0 1594380720",
  "redis.0.parachute.disk.persistent.total 5148114944 1594380720",
  "redis.0.parachute.disk.persistent.used 10657792 1594380720",
  "redis.0.parachute.disk.persistent.used_percent 0 1594380720",
  "redis.0.parachute.disk.persistent.used_threshold 80 1594380720",
  "redis.0.parachute.disk.persistent.free 4852350976 1594380720",
  "redis.0.parachute.disk.persistent.activated 0 1594380720",
]

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	The metrics were succesfully fetched
`401` Unauthorized	The user does not have valid authentication credentials for the target resource
`404` Not Found	Entity not found
`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

Point-In-Time Recovery

The API V1 has the following point-in-time recovery related endpoints available:

Get Available Timerange
Restore to a Target Time

Note: These endpoints are only available for a9s PosgreSQL instances with the continuous archiving setting enabled.

Get Available Timerange

Request

Fetches the available timerange from where a backup can be selected for the restore process of the instance.

Route

GET /v1/instances/:instance_id/pitr

cURL

curl -X GET --cookie test.cookie --cookie-jar test.cookie \
  --location --insecure --header "Authorization: ${bearer_token}" \
  --header "Content-Type: application/json" "${url}/pitr"

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`start_time`	`datetime`	The start (oldest) date of the continuous archiving, from which a backup can be fetched, in ISO 8601 UTC time
`end_time`	`datetime`	The end (newest) date of the continuous archiving, from which a backup can be fetched, in ISO 8601 UTC time

Example:

{
  "start_time":"2022-02-01T20:53:20.000Z",
  "end_time":"2022-02-02T11:45:37.601Z"
}

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

Restore to a Target Time

Request

Triggers the restore process of the instance, which uses the backup closest to the target date.

Route

POST /v1/instances/:instance_id/pitr/restore

Body

The body must be sent in valid JSON format.

Response Field	Type	Description
`target_time`	`datetime`	The date (within range) from which the backup should be fetched, in ISO 8601 UTC time

cURL

curl -X POST --cookie test.cookie --cookie-jar test.cookie \
  --location --insecure --header "Authorization: ${bearer_token}" \
  --header "Content-Type: application/json" "${url}/pitr/restore" \
  --data '{"target_time":"<point_in_time>"}'

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`status`	`string`	The status of the task. The following statuses exist: `queued`, `running`, `done`, `failed`, `deleted`

Example:

{
  "status":"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
`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.
`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.

Browser Compatibility

a9s Service Dashboard ensures compatibily with the following versions. If your version is not in the list, you might encounter issues.

Browser	Supported Versions
Edge	18, 80, 81, 83
Firefox	68, 69, 70, 71, 72, 73, 74, 75, 76
Google Chrome	73, 74, 75, 76, 77, 78, 79, 80, 81, 83
Internet Explorer	Not Supported
Opera	60, 62, 63, 64, 65, 66, 67, 68
Safari	12, 13

Login​

Perform a Backup​

Restore a Backup​

Restore History​

Download a Backup​

Automatic Reload​

Update the Service Instance​

Restart or Recreate the Service Instance​

Instance Metrics​

Size Calculation​

Disks​

API​

Deprecation Notice

How to access the API using cURL​

Authentication​

Authorization​

Headers​

List Backups and Restores​

Request​

Route​

cURL​

Response​

Body​

Backup Object​

Restore Object​

Backup Agent Task Object​

Create Backup​

Request​

Route​

cURL​

Response​

Status​

Body​

Restore Backup​

Request​

Route​

Body​

cURL​

Response​

Status​

Body​

Download Backup​

Request​

Route​

cURL​

Response​

Status​

Body​

API V1​

How to access the API using cURL​

Authentication​

Authorization​

Headers​

Backups​

List All Backups​

Request​

Route​

cURL​

Response​

Body​

Status​

Get a Specific Backup​

Request​

Route​

cURL​

Response​

Body​

Status​

Create a Backup​

Request​

Route​

cURL​

Response​

Body​

Status​

Download a Backup​

Request​

Route​

cURL​

Response​

Login

Perform a Backup

Restore a Backup

Restore History

Download a Backup

Automatic Reload

Update the Service Instance

Restart or Recreate the Service Instance

Instance Metrics

Size Calculation

Disks

API

How to access the API using cURL

Authentication

Authorization

Headers

List Backups and Restores

Request

Route

cURL

Response

Body

Backup Object

Restore Object

Backup Agent Task Object

Create Backup

Request

Route

cURL

Response

Status

Body

Restore Backup

Request

Route

Body

cURL

Response

Status

Body

Download Backup

Request

Route

cURL

Response

Status

Body

API V1

How to access the API using cURL

Authentication

Authorization

Headers

Backups

List All Backups

Request

Route

cURL

Response

Body

Status

Get a Specific Backup

Request

Route

cURL

Response

Body

Status

Create a Backup

Request

Route

cURL

Response

Body

Status

Download a Backup

Request

Route

cURL

Response

Status