Version: 72.0.0

Instance Endpoints

This section describes the usage and specifics of the available instance endpoints of the a9s Public API V1.

info

Before you can access any of the mentioned endpoints, you have to follow the steps mentioned in Accessing the a9s Public API.

Get Instance Overview

This request gets the Service Instance's overview information.

Route

GET /v1/instances/:instance_id

cURL

curl --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 maintenance updates objects	Schema of available maintenance 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`, and `stopped`
`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 tenant (e.g. organization 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 Maintenance Updates Object

Response Field	Type	Description
`name`	`string`	The name of the component with available maintenance updates
`type`	`string`	The type of update of the component
`version`	`string`	The version of the available maintenance 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": "keyvalue8",
      "type": "release",
      "version": "1.0.0"
    }
  ],
  "created_at": "2024-12-19T18:32:55.970Z",
  "id": 1,
  "name": "my-service",
  "plan_id": "77f163d4-0879-482d-bc93-085143bce70e",
  "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": "KeyValue",
      "id": "KeyValue-link",
      "link": "https://a9s-keyvalue-dashboard.example.com/service-instances/db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d/keyvalue"
    },
    {
      "display_name": "Service Instance Dashboard",
      "id": "Dashboard",
      "link": " https://a9s-keyvalue-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.
`202` Accepted	The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`409` Conflict	There is already such action in progress.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Update Instance Settings

This request updates the Service Instance's settings in the a9s Service Broker. These settings allow you to block or forbid Maintenance Updates.

This is the same functionality as the one offered in the a9s Service Dashboard, described in more detail in Update the Service Instance and its Settings.

info

The Platform Operator controls the availability of this endpoint for Application Developers. If the Platform Operator disallows blocking Maintenance Updates, this API endpoint will no longer be accessible.

Route

PATCH /v1/instances/:instance_id/broker/edit

Body

The body must be sent in valid JSON format.

Request Field	Type	Description
`allowed_update_time`	A `hash` containing the settings regarding the blocking of maintenance updates	The schema of this object is defined below in Allowed Update Time Object

cURL

curl -X PATCH --insecure --header "Content-Type: application/json" --header "Authorization: $(bearer_token)" \
  --data '{"allowed_update_time":{"type":"general", "allowed": <value>}}' \
  "${url}/broker/edit"

Response

Body

For success responses, the following fields are defined:

Response Field.	Type	Description
`allowed_update_time`	`hash` containing the update settings regarding the blocking of maintenance updates	The schema of this object is defined below in Allowed Update Time Object
`id`	`string` in GUID format	The ID of the Service Instance itself

Allowed Update Time Object

Response Field	Type	Description
`type`	`string`	An internal specifier for the type of setting. The only available type is `default`
`allowed`	`boolean`	A flag indicating whether the updates are allowed or not

Trigger a Recreate

This request triggers the recreate process of a Service Instance.

Route

PATCH /v1/instances/:instance_id/recreate

cURL

curl -X PATCH --insecure --header "Content-Type: application/json" --header "Authorization: $(bearer_token)" \
  "${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
`200` OK	If the request has been processed successfully.
`202` Accepted	The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`409` Conflict	There is already such action in progress.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Trigger a Restart

Triggers the restart process of a Service Instance.

Route

PATCH /v1/instances/:instance_id/restart

cURL

curl -X PATCH --insecure --header "Content-Type: application/json" --header "Authorization: $(bearer_token)" \
  "${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
`200` OK	If the request has been processed successfully.
`202` Accepted	The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`409` Conflict	There is already such action in progress.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Trigger an Update

This request triggers the update process of for all available maintenance updates of the current a Service Instance.

Route

PATCH /v1/instances/:instance_id/updates

Body

The body must be sent in valid JSON format.

Request Field	Type	Description
`service_id`	`string`	The ID of the Service Offering in CF from which the Service Instance was created

cURL

curl -X PATCH --insecure --header "Content-Type: application/json" --header "Authorization: $(bearer_token)" \
  --data '{"service_id": "<service_id>"}' "${url}/updates"

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
`200` OK	If the request has been processed successfully.
`202` Accepted	The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`409` Conflict	There is already such action in progress.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Get Instance Overview​

Route​

cURL​

Response​

Body​

Available Maintenance Updates Object​

URLs Object​

Status​

Update Instance Settings​

Route​

Body​

cURL​

Response​

Body​

Allowed Update Time Object​

Trigger a Recreate​

Route​

cURL​

Response​

Body​

Status​

Trigger a Restart​

Route​

cURL​

Response​

Body​

Status​

Trigger an Update​

Route​

Body​

cURL​

Response​

Body​

Status​

Get Instance Overview

Route

cURL

Response

Body

Available Maintenance Updates Object

URLs Object

Status

Update Instance Settings

Route

Body

cURL

Response

Body

Allowed Update Time Object

Trigger a Recreate

Route

cURL

Response

Body

Status

Trigger a Restart

Route

cURL

Response

Body

Status

Trigger an Update

Route

Body

cURL

Response

Body

Status