You can use the App Autoscaler API as an interface to App Autoscaler to configure and control scaling apps in your TAS for VMs deployment.
You can also use the App Autoscaler Cloud Foundry command-line interface (cf CLI) plug-in, which offers the same features as the App Autoscaler API. See Using the App Autoscaler CLI.
API endpoints
The API uses the autoscale-api app that runs next to the autoscale app in the autoscaling space of the system org. This is the base URL of all the requests covered in the following sections.
If your system domain is system-domain.com, in most cases you can reach the autoscale app at autoscale.sys.system-domain.com and the API at autoscale.sys.system-domain.com/api/v2. Confirm that you can reach both the app and the API before you proceed.
Authentication
You must pass an access token to each API endpoint. The access token is expected as-is on the Authorization header of each request.
When you are logged in to your foundation with the cf CLI, get an access token by running cf oauth-token.
Note The App Autoscaler API often returns a 404 error when a token is incorrect. If you are receiving a lot of 404 errors, check your access token.
Content type header
To make any PUT or POST requests, you must set the Content-Type header to application/json. If you do not set this, you might see the following error:
"Your token is invalid or the autoscaled application does not exist"
This error can appear regardless of the token you use.
Pagination
Most list calls use pagination. The App Autoscaler API uses a standard form of pagination that is very similar to how the Cloud Foundry API (CAPI) uses pagination.
The following is an example of a paginated response from the App Autoscaler API:
{
"pagination": {
"total_results": 1,
"total_pages": 1,
"last": {
"href": "https://autoscale.sys.example.com/api/v2/apps?space_guid=676e592a-a4e8-43d9-8128-f583c0b45db8&page=1"
},
"next": null,
"first": {
"href": "https://autoscale.sys.example.com/api/v2/apps?space_guid=676e592a-a4e8-43d9-8128-f583c0b45db8&page=1"
},
"previous": null
},
"resources": [
...list of objects...
]
}
Information
GET /api/v2/info
Parameters
None
Returns
A string denoting the App Autoscaler API version.
App bindings
This section lists operations for app bindings.
Apps that are bound to App Autoscaler are represented by the App Autoscaler API as apps.
App binding object
| Name | Type | Description |
|---|---|---|
| created_at | string | The timestamp for when this object was created |
| enabled | Boolean | Enables or disables scaling by App Autoscaler for this app |
| guid | string | The app GUID from CAPI |
| instance_limits.max | integer | The maximum instance count that this app is allowed |
| instance_limits.min | integer | The minimum instance count that this app is allowed |
| scaling_factors.up | integer | The number of instances to increment by when scaling up |
| scaling_factors.down | integer | The number of instances to decrement by when scaling down |
| updated_at | string | The timestamp for when this object was last updated |
Get All app bindings in a space
GET /api/v2/apps
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| space_guid | query | string | true | The GUID of the space from which you want to get all app bindings |
| page | query | integer | false | The page of events to get |
Returns
A paginated list of app bindings.
Get an app binding
GET /api/v2/apps/:app_guid
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| app_guid | path | string | true | The GUID of the app to get the binding for |
Returns
An app binding.
Update an app binding
PUT /api/v2/apps/:app_guid
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| app_guid | path | string | true | The GUID of the app to update the binding for |
| enabled | body | Boolean | false | Enables or disables scaling by App Autoscaler for this app |
| instance_limits.max | body | integer | false | The maximum instance count that this app is allowed |
| instance_limits.min | body | integer | false | The minimum instance count that this app is allowed |
| scaling_factors.up | integer | The number of instances to increment by when scaling up | ||
| scaling_factors.down | integer | The number of instances to decrement by when scaling down |
Returns
An app binding.
Events
This section lists operations to retrieve events.
Scaling events include all scaling decisions made by App Autoscaler and other relevant changes. For example, an app is enabled or disabled.
Event object
| Name | Type | Description |
|---|---|---|
| created_at | string | The timestamp for when this object was created |
| description | string | A description of the event |
| scaling_factor | integer | The change in number of instances |
| updated_at | string | The timestamp for when this object was last updated |
Get all events for an app
GET /api/v2/apps/:app_guid/events
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| app_guid | path | string | true | The GUID of the app to retrieve events for |
| page | query | integer | false | The page of events to get |
Returns
A paginated list of events.
Rules
This section lists operations for rules.
Rules are tied to individual apps, and no one app can have multiple rules of the same category.
Rule object
| Name | Type | Description |
|---|---|---|
| created_at | string | The timestamp for when this object was created |
| comparison_metric | string | The divisor to compare metrics against |
| guid | string | The GUID for this particular object |
| metric | string | The metric on which scaling decisions are made |
| queue_name | string | The name of the queue to monitor for RabbitMQ rules |
| rule_type | string | The type of rule |
| rule_sub_type | string | The subtype of rule |
| threshold.max | float | The threshold beyond which the app is scaled up |
| threshold.min | float | The threshold below which the app is scaled down |
| updated_at | string | The timestamp for when this object was last updated |
Get all rules for an app
GET /api/v2/apps/:app_guid/rules
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| app_guid | path | string | true | The GUID of the app to retrieve rules for |
| page | query | integer | false | The page of events to get |
Returns
A paginated list of rules.
Create a rule
POST /api/v2/apps/:app_guid/rules
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| app_guid | path | string | true | The GUID of the app to create a rule for |
| comparison_metric | body | string | false | The divisor to compare metrics against |
| metric | body | string | false | The metric on which scaling decisions are made |
| queue_name | body | string | false | The name of the queue to monitor for RabbitMQ rules |
| rule_type | body | string | true | The type of rule |
| rule_sub_type | body | string | false | The subtype of rule |
| threshold.max | body | float | true | The threshold beyond which the app is scaled up |
| threshold.min | body | float | true | The threshold below which the app is scaled down |
Returns
A rule.
Replace all rules
PUT /api/v2/apps/:app_guid/rules
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| app_guid | path | string | true | The GUID of the app to set rules for |
| array of rules | body | array | true | An array of rule objects. See Create a Rule. |
Returns
A paginated list of rules.
Delete all rules
DELETE /api/v2/apps/:app_guid/rules
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| app_guid | path | string | true | The GUID of the app to delete rules for |
Returns
A 204 status code and empty body indicating that all rules were deleted.
Get a rule
GET /api/v2/apps/:app_guid/rules/:guid
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| app_guid | path | string | true | The GUID of the app to get a rule for |
| guid | path | string | true | The GUID of the rule to get |
Returns
A rule.
Delete a rule
DELETE /api/v2/apps/:app_guid/rules/:rule_guid
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| app_guid | path | string | true | The GUID of the app to delete a rule for |
| rule_guid | path | string | true | The GUID of the rule to delete |
Returns
A 204 status code and empty body indicating that the rule was deleted.
Scheduled limit changes
This section lists operations for scheduled limit changes (SLCs).
SLCs are jobs scheduled for the future that alter app status, such as enabling, disabling, or instance limits.
Scheduled limit change object
| Name | Type | Description |
|---|---|---|
| created_at | string | The timestamp for when this object was created |
| enabled | Boolean | Whether or not the app is enabled or disabled |
| executes_at | string | The UTC timestamp indicating when this SLC is first executed |
| guid | string | The GUID of this object |
| instance_limits.max | integer | The maximum instance count that is set on the app |
| instance_limits.min | integer | The minimum instance count that is set on the app |
| recurrence | integer | A number that represents the days of the week that the change executes. Each bit in the number represents a day in the following order: sun, mon, tue, wed, thur, fri, sat. For example, repeat mon, wed, fri = 0101010 = 42. |
| updated_at | string | The timestamp for when this object was last updated |
Get All scheduled limit changes for an app
GET /api/v2/apps/:app_guid/scheduled_limit_changes
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| app_guid | path | string | true | The GUID of the app to retrieve SLCs for |
| page | query | integer | false | The page of SLCs to get |
Returns
A paginated list of SLCs.
Create a scheduled limit change
POST /api/v2/apps/:app_guid/scheduled_limit_changes
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| app_guid | path | string | true | The GUID of the app to create an SLC for |
| enabled | body | Boolean | true | Whether or not the app is enabled or disabled |
| executes_at | body | string | true | The UTC timestamp indicating when this SLC is first executed |
| instance_limits.max | body | integer | true | The maximum instance count that is set on the app |
| instance_limits.min | body | integer | true | The minimum instance count that is set on the app |
| recurrence | body | string | true | A number that represents the days of the week that the change executes. Each bit in the number represents a day in the following order: sun, mon, tue, wed, thur, fri, sat. For example, repeat mon, wed, fri = 0101010 = 42. |
Returns
An SLC.
Replace all scheduled limit changes for an app
PUT /api/v2/apps/:app_guid/scheduled_limit_changes
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| app_guid | path | string | true | The GUID of the app to replace SLCs for |
| array of SLCs | body | array | true | An array of SLC objects. See Create a Scheduled Limit Change. |
Returns
A paginated list of SLCs.
Delete all scheduled limit changes for an app
DELETE /api/v2/apps/:app_guid/scheduled_limit_changes
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| app_guid | path | string | true | The GUID of the app to replace SLCs for |
Returns
A 204 status code and empty body indicating that the SLCs were deleted.
Get a scheduled limit change
GET /api/v2/apps/:app_guid/scheduled_limit_changes/:guid
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| app_guid | path | string | true | The GUID of the app to get SLCs for |
| guid | path | string | true | The GUID of the SLC to retrieve |
Returns
An SLC object.
Delete a scheduled limit change
DELETE /api/v2/apps/:app_guid/scheduled_limit_changes/:guid
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| app_guid | path | string | true | The GUID of the app to delete SLCs for |
| guid | path | string | true | The GUID of the SLC to delete |
Returns
A 204 status code and empty body indicating that the SLC was deleted.
