AS3 API Methods Details

The AS3 API supports various Create, Read, Update, and Delete (CRUD) actions. You select specific actions by combinations of HTTP method (such as POST or GET), HTTP URL-path, and properties in request bodies (always JSON).

All AS3 API requests relate to AS3 declarations and to target ADC (BIG-IP) hosts.

A client may supply a declaration with a POST request (although not every POST request has to include one).

All other request methods (GET and DELETE) work with declarations previously supplied via POST and retained by AS3.

The default target ADC for every AS3 request (that is, the target selected when a request does not specify any other) is localhost. In the basic case that means the BIG-IP on which AS3 is running. When AS3 is not running on a BIG-IP, localhost is not a valid target.

API METHODS SUMMARY

Method POST

Use POST to deploy a configuration to a target ADC or for several other actions, including “retrieve”. You must supply a request document with each POST. The request document may be a proper request (see as3-request-schema.json) or a ADC-only declaration (see adc-schema.json).

If your target is something other than localhost, you must use an AS3 request, and specify target options in the body. If you do not specify a target or targetHost, the default target is localhost.

Return to AS3 Class for information about the available actions for POST.

You can use the following URL query parameters for POST:

URL Query Default Description/Notes
show=[base|full|expanded] base base means system returns the declaration as originally deployed (but with secrets like passphrases encrypted), full returns the declaration with all default schema properties populated, expanded includes all URLs, base64s, and other references expanded to their final static values.

For example, with request-property action “deploy”:

POST https://192.0.2.10/mgmt/shared/appsvcs/declare

Deploys the tenants specified in the declaration to target device localhost.

NOTE: the declaration property “updateMode” has a very important effect when you POST with action=”deploy”. When declaration.updateMode is “selective” then AS3 only modifies the Tenants you define in the declaration. When “updateMode” is “complete” then AS3 removes any Tenant which is not defined in the declaration from the target.

POST Actions

You can use the following actions with the POST method in the AS3 Class of your declaration. If you include the AS3 class in your declaration, you MUST include an action (in most cases deploy).

  • deploy
    Deploys the declaration onto the target device. This is the most common action.

  • dry-run
    Similar to the deploy action, dry-run sends the declaration through all validation checks but does not attempt to deploy the configuration on the target device. This can be useful for testing and debugging declarations. The body of the results of this action are “dryRun”: true and “Message”: “success” if the declaration was successful.

  • redeploy
    AS3 stores up to 15 declarations in the target device’s declaration history, the redeploy action allows you to redeploy one of those previous declarations. To use redeploy, you should also include a “redeployAge”: in the AS3 class (under redeploy) that has a value between 0-15. If you do not include a redeployAge, AS3 defaults to 0, which means the most recently deployed declaration. You can use GET with ?age=list at the end of the URI to retrieve a list of the available declarations and their ages (see the GET examples in the following section).

  • retrieve
    The retrieve action returns the entire declared configuration, which is the same as using the GET method (for localhost, we recommend using GET and not the retrieve action). The body of your declaration would include only “class”: “AS3”, and “action”: “retrieve”.

  • remove
    The remove action removes the entire declared configuration, which is the same as using the DELETE method (for localhost, we recommend using DELETE and not the remove action). The body of your declaration would include only “class”: “AS3”, and “action”: “remove”.

Method GET

Use GET to retrieve a declaration (with all or just some Tenants) or an index of stored declarations. Select the data you want by appending elements to the main AS3 URL path (/mgmt/shared/appsvcs/declare). By default (GET just the main URL path) GET returns the base declaration for all Tenants on target localhost.

You can use the following URL query parameters for GET:

URL Query Parameter Default Description/Notes
show=[base|full|expanded] base base means system returns the declaration as originally deployed (but with secrets like passphrases encrypted), full returns the declaration with all default schema properties populated, expanded includes all URLs, base64s, and other references expanded to their final static values.
age=[list|{0-15}] 0 If you use ?age=0-15 asks for a declaration of the given age (0 means most-recently deployed), and “list” asks for a list of available declarations with their ages. If this element is not present, the default age is 0. By default, list only shows 4 declarations, this is configurable using historyLimit in the AS3 class.

Additionally, you can specify the tenant(s) you want AS3 to return, with multiple tenants separated by commas (see the third example in the following list).

GET examples

GET https://192.0.2.10/mgmt/shared/appsvcs/declare

This returns the most-recently-deployed declaration with all tenants that AS3 knows about.

GET https://192.0.2.10/mgmt/shared/appsvcs/declare?show=full

This returns the most-recently-deployed declaration for all tenants with all schema defaults filled in.

GET https://192.0.2.10/mgmt/shared/appsvcs/declare/T1,T3?show=expanded

This returns the most-recently-deployed declaration but includes only Tenants T1 and T3, and with the declaration completely expanded.

GET https://192.0.2.10/mgmt/shared/appsvcs/declare?age=list

This returns a list of available declarations and their ages. By default, list only shows the last four declarations. You can configure this using historyLimit in the AS3 class, for example, you would add “historyLimit”: 15, to the AS3 class at the same level as action.

GET https://192.0.2.10/mgmt/shared/appsvcs/declare/T1?show=full&age=1

This returns a the second-most-recently-deployed declaration for the Tenant T1.

You can also retrieve declarations or the declaration index using POST instead of GET. You must POST a request document with action=retrieve. If you would like to retrieve a declaration other than localhost, see the Method POST. For localhost, we recommend using GET to retrieve declarations.

Method DELETE

Use DELETE to remove configurations for one or more declared Tenants from the target ADC. If you do not specify any Tenants, DELETE removes all of them, which is to say, it removes the entire declared configuration. Indicate the target device and Tenants to remove by appending elements to the main AS3 URL path (/mgmt/shared/appsvcs/declare). By default (just main URL) DELETE removes all Tenants from target localhost.

You can use the following URL query parameters and URL Path elements for DELETE:

URL Query Parameter Default Description/Notes
show=[base|full|expanded] base base means system returns the declaration as originally deployed (but with secrets like passphrases encrypted), full returns the declaration with all default schema properties populated, expanded includes all URLs, base64s, and other references expanded to their final static values.

Additionally, you can specify the tenant(s) you want AS3 to delete, with multiple tenants separated by commas (see the second example in the following list).

DELETE examples:

DELETE https://192.0.2.10/mgmt/shared/appsvcs/declare

removes all tenants

DELETE https://192.0.2.10/mgmt/shared/appsvcs/declare/T1,T2,T5

removes Tenants T1, T2, and T5 leaving the rest of the most recent declared configuration for localhost in place (assuming there are other Tenants, such as T3 and T4).

You can also remove declarations or particular Tenants using POST instead of DELETE. You must POST a request document with action=remove and a suitable declaration. For localhost, we recommend using DELETE to remove declarations.