API V1 Endpoints
This section describes the usage and specifics of the available endpoints of the a9s Public API V1.
List All Backups
This request lists all of the Service Service Instance's available backups.
Route
GET /v1/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
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
This request returns the information of the specified Service Instance's backup.
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 session.cookie --cookie-jar session.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
This request triggers the creation of a new Service 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
Route
POST /v1/instances/:instance_id/backups
: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"
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
This request downloads the given backup of a given Service Instance.
Route
GET /v1/instances/:instance_id/backups/:id/download
:instance_idMUST be the ID of a previously provisioned Service Instance.:idMUST be the ID of a previously performed backup.
cURL
curl --cookie session.cookie --cookie-jar session.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 |
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.
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 --cookie session.cookie --cookie-jar session.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
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 --cookie session.cookie --cookie-jar session.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
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 --cookie session.cookie --cookie-jar session.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 |
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>
Get Backups Configuration
This request gets the information regarding the Service Instance's backups configuration.
Route
GET /v1/instances/:instance_id/backups-config
: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-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 a Service 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
This request sets the information regarding the Service Instance's backups' configuration. This is currently limited to setting the backups' encryption key.
In order to be able to decrypt a downloaded backup, the encryption key MUST be known/set before triggering said backup.
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 session.cookie --cookie-jar session.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 |
Prepare a Disaster Recovery
This request prepares the required information for an Service Instance's disaster recovery.
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 session.cookie --cookie-jar session.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
This request performs an Service Instance's disaster recovery in the destination Service Instance.
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 Service Instance's backups |
encryption_key | string | true | The key which the Backup Manager is using to encrypt backups |
cURL
curl -X POST --cookie session.cookie --cookie-jar session.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 |
Get Instance Overview
This request gets the Service Instance's overview information.
Route
GET /v1/instances/:instance_id
cURL
curl --cookie session.cookie --cookie-jar session.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 a Service Instance was created, in ISO 8601 UTC time |
id | int | The id of a Service Instance within the Data Service |
name | string | The given name of a Service Instance |
plan_id | string | The id of the plan a Service Instance was created under |
service_id | string | The id of the Data Service from which a Service Instance was created |
state | string | Current state of a Service 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 a Service 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
This request triggers the recreate process of a Service Instance.
Route
PATCH /v1/instances/:instance_id/recreate
cURL
curl -X PATCH --cookie session.cookie --cookie-jar session.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
Triggers the restart process of a Service Instance.
Route
PATCH /v1/instances/:instance_id/restart
cURL
curl -X PATCH --cookie session.cookie --cookie-jar session.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
This request triggers the update process of for all available updates of the current a Service 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 a Service Instance was spawned from |
cURL
curl -X PATCH --cookie session.cookie --cookie-jar session.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
This request displays the metrics of your Service Instance.
Route
GET /v1/instances/:instance_id/metrics?quantity=x
:instance_idMUST be the ID of a previously provisioned Service Instance.quantityNumber 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
Currently the supported DataPoint type is system.
Load
The following are the supported specifics for the system DataPoint type.
| 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 |
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.
| 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 successfully 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 - Get Available Time Range
This request fetches the available time range from where a backup can be selected for the restore process of the instance.
This endpoint is only available for a9s PostgreSQL instances with the continuous archiving setting enabled.
Route
GET /v1/instances/:instance_id/pitr
cURL
curl -X GET --cookie session.cookie --cookie-jar session.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 |
Point-In-Time Recovery - Restore to a Target Time
This request triggers the restore process of a Service Instance, which uses the backup closest to the target date.
This endpoint is only available for a9s PostgreSQL instances with the continuous archiving setting enabled.
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 session.cookie --cookie-jar session.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. |