API - HTTP PATCH Support

Overview

This guide explains the usage of HTTP PATCH method.

Avi Vantage supports use of PATCH to perform the following operations:

Update scalar fields (string, bool, int32, and so on).
Add a new entry to a list in an object.
Update an entry in a list in an object.
Unset scalar fields. This causes the fields to be reset to their default values, if applicable.
Delete an entry from a list in an object. > Note: According to section 5.1.1 of RFC2616, “The Method token indicates the method to be performed on the resource identified by the Request-URI. The method is case-sensitive.” Therefore, spell it “PATCH” to avoid “400 bad request” errors from Avi Vantage when executing the HTTP PATCH request.

Editing Nested Fields

In the current release, editing nested fields using PATCH is supported only to a field depth of 1 (one). PATCH is not supported for editing objects with deep nesting characteristics. To accomplish an edit to a nested field, PATCH will expect the data to be in the following form:

{
    "add": {

    }
}

{
    "replace": {

    }
}

{
    "delete": {

    }
}

In the case of scalar fields, both “add” or “replace” is equivalent in that they replace the value of the scalar field with the value provided. In the case of a list, “add” indicates that the specified set of entries needs to be added to the list and “replace” indicates that the list itself is replaced with what is specified in the request. “delete” is used to remove specified entries from the list.

Examples

The following examples use PATCH to update server information in a pool. The pool is identified by its UUID.

Add Servers to a Pool

This request to the Avi Vantage API adds two new servers (1.1.1.1 and 1.1.1.2) to an existing pool.

API: /api/pool/pool_uuid
Data:
{
    "add": {
        "servers": [
            {
                "ip": {
                    "addr": "1.1.1.1",
                    "type": "V4"
                }
            },
            {
                "ip": {
                    "addr": "1.1.1.2",
                    "type": "V4"
                }
            }
        ]
    }
}

Update Server Information in a Pool

This request to the Avi Vantage API updates one of the servers in an existing pool:

API: /api/pool/pool_uuid
Data:
{
    "add": {
        "servers": [
            {
                "ip": {
                    "addr": "1.1.1.1",
                    "type": "V4"
                },
                "ratio": 10
            }
        ]
    }
}

Note: If a field is an array of structures, each structure is typically identified by a key (combination of the fields within the structure). This is used to identify the element in the list to update. In the case of pool servers, the server key is identified by “ip”, “port”.

Replace Servers in a Pool with a new set of Servers

This request replaces the entire server list with a new server list. The other fields of the pool remain intact.

API: /api/pool/pool_uuid
Data:
{
    "replace": {
        "servers": [
            {
                "ip": {
                    "addr": "3.3.3.3",
                    "type": "V4"
                },
            },
            {
                "ip": {
                    "addr": "3.3.3.4",
                    "type": "V4"
                },
            }
        ]
    }
}

Delete a Server from a Pool

This request deletes one of the servers from an existing pool:


API: /api/pool/pool_uuid
Data:
{
    "delete": {
        "servers": [
            {
                "hostname": "www.example.com",
                "ip": {
                    "addr": "3.3.3.3",
                    "type": "V4"
                },
                "resolve_server_by_dns": true
            }
        ]
    }
}

Updating Scalar Fields

The examples in this section set some scalar fields. The following request enables HTTP request queuing and sets the default server port to 8080.

API: /api/pool/pool_uuid
Data:
{
    "replace": {
        "request_queue_enabled": True,
        "default_server_port": 8080
    }
}

The following request resets the default server port to the system default, by deleting its explicit setting from the pool.

API: /api/pool/pool_uuid
Data:
{
    "delete": {
        "default_server_port": 8080
    }
}

Supported Objects

PATCH is officially supported for the following objects and fields:

Object	Fields
Cloud	linuxserver.hosts
GslbService	enabled
IpAddrGroup	addrs prefixes ranges
MicroServiceGroup	service_refs
Pool	health_monitor_refs servers
StringGroup	kv type
SystemConfiguration	dns_virtualservice_refs global_tenant_config snmp_configuration.community
VirtualService	http_policies

Asynchronous Patch

Adding pools and deleting pools at a high rate requires applying patches at a high rate. The size of the deployment often adds more load on the Controller and increases the latency.

Starting with Avi Vantage version 18.2.11, the Asynchronous Patch feature is introduced. Using this feature, patch requests are queued, consolidated in fixed intervals, and updated together with minimal latency.

Note: This feature is recommended only in case the deployment size is large.

When async_patch_merge_period is 0 in Controller properties all PATCH calls on pool with ?async_mode=true will be converted into synchronous call and 200 response will be returned.````

Using the Asynchronous Patch Update

By default, this feature is disabled.

To enable Asynchronous Patch, change the async_patch_merge_period in the Controller properties from 0 (default value) to the required interval (30-120 seconds).
Pass the async_mode as a query parameter in the patch request.

For example, PATCH /api/pool/<pool-uuid>?async_mode.

The response will display a unique patch_id, which can be used to view the status of the request.

The patch consolidate is initiated, thereby merging the pending requests in the queue.

Review the status using a GET request on /api/pool-async/status/<patch_id>.

The status is displayed as follows:


 {
                 "uuid": <uuid of the pool>,
    
                 "status": "QUEUED | IN_PROGRESS | SUCCESS | FAIL",
    
                 "created": <timestamp of request creation>,
    
                 "error_message": <error message in case of failure>,
    
                 "status_code": <status code for server PATCH>
    
            }

Caveats

Currently, this feature is available only for the servers field (with IP4) in the pool object
This feature is limited to only adding or deleting servers in a pool
All patch requests to the Controller within an async_patch_merge_period should have the same API version (HTTP_X_AVI_VERSION)
Patch updates will not be installed until the next update cycle, as defined in the time interval. Therefore, the patch updates are not real time