PUT method usage and considerations

The PUT method updates an instance of a resource by replacing the existing resource with the resource provided in the request body.

Configuration attributes that are set at the time a resource is created and that cannot be changed afterward are called immutable attributes. Configuration attributes that can be changed after a resource is created are called mutable or writable attributes. The PUT method is used replace writable attributes only.

  • Not all resources support the PUT method. For information about the methods supported for a resource, see the ArubaOS-CX REST API Reference. The REST API must be in read-write mode to see all the PUT methods supported.

  • The URI must specify a specific resource, not a collection.

  • The URI must specify a resource that currently exists.

  • For almost all resources, the PUT method is implemented as a strict replace operation.

    All mutable configuration attributes are replaced. Any mutable attribute that the JSON data in request body does not include is either removed (if there is no default value) or reset to its default value.

PUT request body requirements

The JSON data in the request body must include mutable (writable) configuration attributes only.

The JSON model you must use for the PUT method request body is different from the JSON model used for the GET or the POST method.

The JSON model of a PUT method for a resource contains the mutable attributes only. In contrast, the JSON models for GET and POST methods can include both mutable and immutable attributes.

See the ArubaOS-CX REST API Reference for the JSON model of a PUT method for a resource.

PUT behavior

The PUT operation is a replace operation—not an update operation—because the resource instance in the request body replaces every changeable configuration attribute of the existing resource. PATCH partial updates are not supported.

CAUTION:

Any mutable attribute that the JSON data in request body does not include is either removed (if there is no default value) or reset to its default value.

For example:

  • If you attempt a PUT operation on the system to change the host name, and you supply only the host name, you will destabilize the switch because the other attributes will be reset to their defaults, which might be empty.

  • If you attempt to change the name of a VLAN and supply only the name in the PUT request, every other attribute in that VLAN is set to its default of empty.

Exceptions to the PUT strict replace behavior

For Network Analytics Engine agents, the PUT behavior is not a strict replace implementation. You can enable or disable agents without the supplying the entire set of configuration attributes in the PUT request body. For more information about the Network Analytic Engine resources, see the Network Analytics Engine Guide.