AS3 API Methods Details

The AS3 API supports 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 certain 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.

Important: AS3 3.7.0 introduces new behavior for asynchronous mode. Even if you have asynchronous mode set to false, after 45 seconds AS3 sets asynchronous mode to true (API swap), and returns an async response. This allows you to use GET to poll for status (you should see a 202 status until the declaration is complete). This typically occurs only with very large declarations to BIG-IP or most declarations to BIG-IQ; if the declaration completes in less than 45 seconds, AS3 does not modify asynchronous mode.

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.
async=[true|false] false AS3 3.5.0+: Setting async to true causes AS3 to respond with a 202 status and a request ID which you can later use in a GET request to a new /task endpoint to get the results. Typically only used with extremely large declarations which take a long time for AS3 to process. The record IDs expire after 24 hours. When you retrieve a record, AS3 deletes the record along with any expired records. A GET to /task with no record ID specified returns (and deletes) all records.

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

  • patch
    Modifies and re-submits the stored declaration with changes specified according to the JSON Patch standard. To use patch, you should also include a “patchBody”: in the AS3 class. For more information on JSON Patch, see https://tools.ietf.org/html/rfc6902.

  • 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). 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”).

In AS3 3.5.0 and later, if you used the ?async=true query parameter to send a large declaration, you can use a GET request to the /task endpoint (for example /mgmt/shared/appsvcs/task/<record ID>) with the record ID returned by the POST to see the status of the processing (and the results if it is finished). Note that you cannot use the async query parameter with GET, only POST.

You can use the following URL query parameters for GET (Note: filterClass was introduced in AS3 3.6.0 and will only work on 3.6.0 and later):

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 ?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.
filterClass=[AS3 Class] 0 You can use filterClass to retrieve results for only a specific AS3 class. For example ?filterClass=HTTP_Profile only returns the HTTP Profile portions of the declaration. You can only use filterClass once in a single GET request.

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

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.

GET https://192.0.2.10/mgmt/shared/appsvcs/task/8c561063-b0af-4e0b-8115-f6248b76c484

This returns the status of previously POSTed declaration using the async=true query parameter. If the declaration has finished processing, AS3 returns the results of the declaration. Once you retrieve a record, AS3 deletes the record along with any expired records. A GET to /task with no record ID specified returns (and deletes) all records.

GET  https://192.0.2.10/mgmt/shared/appsvcs/declare/T1?filterClass=HTTP_Profile

This returns only items in the declaration that match the HTTP_Profile class.

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 (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. See Using PATCH to add an application to a tenant for additional information.
[{"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": "copy", "from": "/tenant1/app1/pool1_original", "path": "/tenant1/app2/pool1_clone" }]


Using PATCH to add an application to a tenant

This section attempts to clarify how to use PATCH to add an application. PATCH is dependent on the path property. Everything is relative to the original declaration on that URL (i.e., the “declaration”: {…}). It can be helpful to think of PATCH as directly modifying that declaration object tree.

Note

In this first example, we show how you might use PATCH, but not get the results you intend.

In your main URL, GET returns the following configuration syntax:

GET {host}/mgmt/shared/appsvcs/declare

"declaration": {
    "tenant1": {
      "app1": { ... },
      "app2": { ... }
    },
    "tenant2": {
      "app1": { ... },
      "app2": { ... }
    }
}

If you use PATCH like the following example:

PATCH {host}/mgmt/shared/appsvcs/declare

"path": "/tenant1"
"op": "add",
"value": {
    "app3": {
      "class": "Application",
      ...
    }
}

You are indicating that you want to replace tenant1 with the value of the app3 object (or create it if it doesn’t exist), per the RFC (see https://tools.ietf.org/html/rfc6902#section-4.1 and https://tools.ietf.org/html/rfc6902#appendix-A.1). However, AS3 expects an object with “class”: “Tenant” at the path “/tenant1”, so you will get an invalid declaration error:

{
    "code": 422,
    "declarationFullId": "",
    "message": "declaration is invalid",
    "errors": [
        "/tenant1: should have required property 'class'"
    ]
}

In this second example, we show how to use PATCH to add a new app in a particular tenant.

Starting with our original declaration:

GET {host}/mgmt/shared/appsvcs/declare

"declaration": {
    "tenant1": {
      "app1": { ... },
      "app2": { ... }
    },
    "tenant2": {
      "app1": { ... },
      "app2": { ... }
    }
}

If you want to add a 3rd app to tenant1, you would use the following PATCH (compare the path and value to the earlier example):

PATCH {host}/mgmt/shared/appsvcs/declare

"path": "/tenant1/app3"
"op": "add",
"value": {
    "class": "Application",
    "template": "generic"
    ...
}

The resulting declaration looks like the following:

GET {host}/mgmt/shared/appsvcs/declare

"declaration": {
    "tenant1": {
      "app1": { ... }
      "app2": { ... }
      "app3": {
          "class": "Application",
          "template": "generic"
          ...
      }
    },
    "tenant2": {
      "app1": { ... },
      "app2": { ... }
    }
}