Using the App Autoscaler API

Page last updated:

This topic explains how to use the App Autoscaler API.

You can use the App Autoscaler API as an interface to App Autoscaler. You can also use the App Autoscaler Cloud Foundry command-line interface (cf CLI) plugin, which offers the same features as the App Autoscaler API. See Using the App Autoscaler CLI.

API Endpoints

The API is exposed by 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 sections below.

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 a 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. This is similar to service binding in CAPI.

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

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 number of instances that the app was scaled by
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.