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.

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

  • The JSON model you use for a resource PUT operation is different from the JSON model used for the GET operation. For example, immutable attributes are omitted from the PUT JSON model of a resource. See the ArubaOS-CX REST API Reference for the JSON model used the PUT operation of a resource.

  • For almost all resources, the PUT method is implemented as a strict replace operation. All changeable configuration attributes are replaced and must be provided in the JSON data in the request body.

PUT request body requirements

  • Configuration attributes that are set at the time a resource is created and that cannot be changed afterward are called immutable attributes. The JSON data must not include any immutable attributes.

  • The JSON data in the request body must include the mutable—or changeable—configuration attributes only. Any mutable attributes not supplied in the request body are set to their default values.

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. 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 back to its default of empty.

Exceptions to the strict PUT 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 ArubaOS-CX Network Analytics Engine guide for your switch and software release.