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 or a ADC-only declaration.

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, if you do not include an action, it defaults to deploy.

  • deploy
    Deploys the declaration onto the target device. This is the most common action, and is the default if you do not specify an action in AS3 v3.1.0 and later.

  • 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 also use /mgmt/shared/appsvcs/info to retrieve information on the version and release of AS3 you are using, as well as the current version of the AS3 schema (and minimum required schema version). Note that if you attempt to use GET, but you do not currently have any AS3-produced configuration on the target device, the system responds with a 204 HTTP status (“The server successfully processed the request and is not returning any content”).

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.

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

This returns version and release information for the instance of AS3 you are using. It also shows current and minimum required versions of the AS3 schema.

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


Method PATCH

Use PATCH to modify an existing declaration without having to resend the entire declaration. For detailed information on JSON PATCH, see https://tools.ietf.org/html/rfc6902 (note that AS3 does not support the test operation object). With PATCH, you use an operation object that tells AS3 what you want to do, and then a path to the object in the original declaration. In some operation objects you include a value, in others, you include from, see the following table for details.

In the request body, use the following example syntax (see the PATCH operation objects table for examples), as some operations include from and do not include value:

[
    {
        "op": "<operation object>",
        "path": "<path with JSON pointer>",
        "value": "<value to assign to object in the path>"
     }
 ]


PATCH operation objects

You can use the following operation objects with the PATCH method. If you include the AS3 class in your declaration, you MUST include an action (in most cases deploy). In the examples in the following table, we condense the examples onto a single line to save space, you may use either a single line or multiple lines when submitting your PATCH, as long as it is valid JSON. You can also see https://tools.ietf.org/html/rfc6902#appendix-A for PATCH examples in the RFC.

Operation object Description Example
add Use the add operation to add objects to an existing declaration, such as additional servers to a pool. You must specify the exact path to the object to which you are adding something, including location in an array if applicable. In the example on the right, our initial declaration included a pool, and included two member items in the members array: the first on port 80, and a second on port 8080. In this case, after members we add /0/ to signify we want to add the server to the first member using port 80. If we wanted to add the server address to the port 8080 member, we’d change /0/ to /1/.

For add only:
For arrays: if the order you want to insert the new object is not important, use a - (dash) in place of the 0-based index. AS3 adds the new value to the end of the array. Otherwise, if the path points to the index, AS3 inserts the value into the array at the specified index.
For members/properties of an object: If the target in the path does not exist, AS3 adds that property to the object. If it exists, AS3 replaces the property value.

In the second example, we use add to modify the Slow Ramp Time from the default of 10 to 20.
[{"op": "add", "path": "/tenant1/app1/pool1/members/0/serverAddresses/-", "value": "10.1.2.3" }]
[{"op": "add", "path": "/tenant1/app1/pool1/slowRampTime", "value": "20" }]
remove Use the remove operation to remove objects from an existing declaration. Remove does not use a value, only the operation object and the path. If you do include a value, AS3 ignores it; AS3 only removes the object specified in the path. You must be specific in the path and include the location in the array index (which starts at 0). In the example, AS3 removes the 3rd serverAddress from pool 1. [{"op": "remove", "path": "/tenant1/app1/pool1/members/0/serverAddresses/2" }]
replace Use the replace operation to change one value to another. Use path to specify the value you want to change, and value to specify the new value. Again, you must be specific in the path and include the location in the array index if modifying an array member, or the property name if modifying an object member.

IMPORTANT: When using replace, the path must exist (meaning the original declaration MUST include the object in the path). If the property you are attempting to replace is not in the base declaration (use GET with ?show=base at the end of the URI to view the base declaration), you must use add and not replace, otherwise you get an error stating the path does not exist. For example, the property enable does not appear in the base declaration (but defaults to true). To use PATCH to disable a pool member by changing the value of enable, you would use add, for example [{"op": "add", "path": "/tenant1/app1/pool1/members/0/enable", "value": false }].

In the example, AS3 replaces the existing 4th server address with 10.1.2.5.
[{"op": "replace", "path": "/tenant1/app1/pool1/members/0/serverAddresses/3", "value": "10.1.2.5" }]
move Use the move operation to remove the value at a specified location and add it to the target location. For move, you must also include a from location in addition to the path. Like remove, you do not include a value, and if you do, AS3 ignores it. Because move is a remove and add operation, you can specify a new object in the path (but from must exist).
In the first example, AS3 moves the 4th server address from pool1 to the 4th server address in pool1_new.
In the second example, AS3 renames pool1_new to pool2 (by using move operation which removes pool1_new and adds it back with the new name).
[{"op": "move", "from": "/tenant1/app1/pool1/members/0/serverAddresses/3", "path": "/tenant1/app1/pool1_new/members/0/serverAddresses/3" }]
[{"op": "move", "from": "/tenant1/app1/pool1_new", "path": "/tenant1/app1/pool2" }]
copy Use the copy operation to copy the value at a specified location to the target location. This operation also does not use a value. In the example, AS3 copies the pool1_original pool from app1 and adds it to app2 as pool1_clone. [{"op": "move", "from": "/tenant1/app1/pool1_original", "path": "/tenant1/app2/pool1_clone" }]