Product Documentation

Simplify Management Operations with an idempotent API

Sep 01, 2016

You can add or update NetScaler resources seamlessly, with a single API. Previously, an attempt to add a resource that was already configured, or to update a resource that was not yet configured, caused an error.

If you enable the “idempotent” query parameter (“idempotent=yes”) in any POST request, NITRO executes the request in an idempotent manner. An idempotent HTTP method is an HTTP method that can be called many times without different results, and POST is desinged as a non-idempotent method.


Use POST request with “idempotent” option if you are unsure whether the resource in the request exists on NetScaler or not.

This API  hides the inconsistencies between parameter lists of POST and PUT operations. For some NITRO resources, certain parameters are accepted only on PUT not in POST, or vice versa. By using this idempotent API, you can overcome such challenges.


  • If a resource is already configured and you try to add the same resource again, the resource is  "updated," but the arguments already present are not unset. For example, if a  load balancing virtual server named  "V1" is configured to use the round robin load balancing method, and you try to ADD an lbvserver named "V1" without specifying a value for "lbmethod" in the request, the NetScaler appliance does not  unset "lbmethod" to its default value of "leastconnection."

In the following example, “preferredntpserver” is allowed only in PUT, but when given in POST request with idempotent=yes, NITRO internally adds the ntpserver and updates it with given properties.

HTTP Method



Request Headers 복사


Content-Type: application/json

Request Payload 복사


                “ntpserver”:{“servername”:“ntp1”,“minpoll”:“4”,“preferredntpserver”: “yes”}


  • Response

HTTP Status Code on Success
         200 OK

HTTP Status Code on Failure
4xx <string> (for general HTTP errors) or 5xx <string> (for NetScaler-specific errors). The response payload provides details of the error.