NetScaler SDX

REST web services

May 2, 2023

Contributed by:

S S

REST (Representational State Transfer) is an architectural style based on simple HTTP requests and responses between the client and the server. REST is used to query or change the state of objects on the server side. In REST, the server side is modeled as a set of entities where each entity is identified by a unique URL.

Each resource also has a state on which the following operations can be performed:

Create. Clients can create new server-side resources on a “container” resource. You can think of container resources as folders, and child resources as files or subfolders. The calling client provides the state for the resource to be created. The state can be specified in the request by using XML or JSON format. The client can also specify the unique URL that identifies the new object. Alternatively, the server can choose and return a unique URL identifying the created object. The HTTP method used for create requests is POST.
Read. Clients can retrieve the state of a resource by specifying its URL with the HTTP GET method. The response message contains the resource state, expressed in JSON format.
Update. You can update the state of an existing resource by specifying the URL that identifies that object and its new state in JSON or XML, using the PUT HTTP method.
Delete. You can destroy a resource that exists on the server-side by using the DELETE HTTP method and the URL identifying the resource to be removed.

In addition to these four CRUD operations (Create, Read, Update, and Delete), resources can support other operations or actions. These operations use the HTTP POST method, with the request body in JSON specifying the operation to be performed and parameters for that operation.

SDX NITRO APIs are categorized depending on the scope and purpose of the APIs into system APIs and configuration APIs.

System APIs

The first step towards using NITRO is to establish a session with the SDX appliance and then authenticate the session by using the administrator’s credentials.

Specify the user name and password in the login object. The session ID that is created must be specified in the request header of all further operations in the session.

Note: You must have a user account on that appliance. The configurations that you can perform are limited by the administrative role assigned to your account.

To connect to an SDX appliance with IP address 10.102.31.16 by using the HTTPS protocol:

URL https://10.102.31.16/nitro/v2/config/login/
HTTP Method POST
Request
- Header
```
 Content-Type:application/vnd.com.citrix.sdx.login+json
 
```
  Note: Content types such as ‘application/x-www-form-urlencoded’ that were supported in earlier versions of NITRO can also be used. Ensure that the payload is the same as used in earlier versions. The payloads provided in this documentation are only applicable if the content type is of the form ‘application/vnd.com.citrix.sdx.login+json’.
- Payload
```
 {
     "login":
     {
         "username":"nsroot",
         "password":"verysecret"
     }
 }
 
```

Response Payload

Header

 HTTP/1.0 201 Created
 Set-Cookie:
 NITRO_AUTH_TOKEN=##87305E9C51B06C848F0942; path=/nitro/v2
 <!--NeedCopy-->

Note: Use the session ID in all further NITRO operations on the appliance.

Note: By default, the connection to the appliance expires after 30 minutes of inactivity. You can modify the timeout period by specifying a new timeout period (in seconds) in the login object. For example, to modify the timeout period to 60 minutes, the request payload is:

{
    "login":
    {
        "username":"nsroot",
        "password":"verysecret",
        "timeout":3600
    }
}
<!--NeedCopy-->

You can also connect to the appliance to perform a single operation, by specifying the user name and password in the request header of the operation. For example, to connect to an appliance while creating a NetScaler instance:

URL
HTTP Method

Request

Header

 X-NITRO-USER:nsroot
 X-NITRO-PASS:verysecret
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 <!--NeedCopy-->

Payload

 {
     "ns":
     {
         ...
     }
 }
 <!--NeedCopy-->

Response.
- Header
```
 HTTP/1.0 201 Created
 
```

To disconnect from the appliance, use the DELETE method:

URL
HTTP Method DELETE

Request

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.login+json
 <!--NeedCopy-->

Configuration APIs

The NITRO protocol can be used to configure the resources of the SDX appliance.

Each SDX resource has a unique URL associated with it, depending on the type of operation to be performed. URLs for configuration operations have the format: http://<IP>/nitro/v2/config/<resource_type>

Create a resource

To create a resource (for example, a NetScaler instance) on the SDX appliance, specify the resource name and other related arguments in the specific resource object. For example, to create a NetScaler instance named vpx1:

URL
HTTP Method

Request

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 <!--NeedCopy-->

Payload

 {
     "ns":
     {
         "name":"vpx1",
         "ip_address":"192.168.100.2",
         "netmask":"255.255.255.0",
         "gateway":"192.168.100.1",
         "image_name":"nsvpx-9.3-45_nc.xva",
         "vm_memory_total":2048,
         "throughput":1000,
         "pps":1000000,
         "license":"Standard",
         "profile_name":"ns_nsroot_profile",
         "username":"admin",
         "password":"admin",
         "network_interfaces":
         [
             {
                 "port_name":"10/1"
             },
             {
                 "port_name":"10/2"
             }
         ]
     }
 }
 <!--NeedCopy-->

Retrieve resource details and statistics

SDX resource details can be retrieved as follows:

To retrieve details of a specific resource on the SDX appliance, specify the id of the resource in the URL.
To retrieve the properties of resources based on some filter, specify the filter conditions in the URL.

The URL has the form: http://<IP>/nitro/v2/config/<resource_type>?filter=<property1>:<value>,<property2>:<value>
If your request is likely to result in many resources returned from the appliance, you can retrieve these results in chunks by dividing them into “pages” and retrieving them page by page.

For example, assume that you want to retrieve all NetScaler instances on an SDX that has 53 of them. Instead of retrieving all 53 in one large response, configure the results to be divided into pages of 10 NetScaler instances each (6 pages total). Then, retrieve them from the server page by page.

You specify the page count with the page size query string parameter and use the page number query string parameter to specify the page number that you want to retrieve. The URL has the form: http://<IP>/nitro/v2/config/<resource_type>?pageno=<value>&pagesize=<value>

You do not have to retrieve all the pages, or retrieve the pages in order. Each request is independent, and you can even change the page size setting between requests.

Note: To have an idea of the number of resources that are likely to be returned by a request, you can use the count query string parameter to ask for a count of the resources to be returned, rather than the resources themselves. To get the number of NetScaler instances available, the URL would be http://<IP>/nitro/v2/config/<resource_type>?count=yes

To retrieve the configuration information for the NetScaler instance with ID 123456a:

URL
HTTP Method GET

Update a resource

To update an existing SDX resource, use the PUT HTTP method. In the HTTP request payload, specify the name and the other arguments that have to be changed. For example, to change the name of the NetScaler instance with ID 123456a to vpx2:

URL
HTTP Method

Request Payload

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 <!--NeedCopy-->

Payload

 {
     "ns":
     {
         "name":"vpx2",
         "id":"123456a"
     }
 }
 <!--NeedCopy-->

Delete a resource

To delete an existing resource, specify the name of the resource to be deleted in the URL. For example, to delete a NetScaler instance with ID 123456a:

URL
HTTP Method

Request

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 <!--NeedCopy-->

Bulk operations

You can query or change multiple resources simultaneously and thus minimize network traffic. For example, you can add multiple NetScaler SDX appliances in the same operation. You can also add resources of different types in one request.

To account for the failure of some operations within the bulk operation, NITRO allows you to configure one of the following behaviors:

Exit. When the first error is encountered, the execution stops. The commands that were run before the error are committed.
Continue. All the commands in the list are run even if some commands fail.

Note: Configure the required behavior in the request header using the X-NITRO-ONERROR parameter.

To add 2 NetScaler resources in one operation and continue if one command fails:

URL.
HTTP Method.

Request Payload.

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 X-NITRO-ONERROR:continue
 <!--NeedCopy-->

Payload

 {
     "ns":
     [
         {
             "name":"ns_instance1",
             "ip_address":"10.70.136.5",
             "netmask":"255.255.255.0",
             "gateway":"10.70.136.1"
         },
         {
             "name":"ns_instance2",
             "ip_address":"10.70.136.8",
             "netmask":"255.255.255.0",
             "gateway":"10.70.136.1"
         }
     ]
 }
 <!--NeedCopy-->

To add multiple resources (NetScaler and two MPS users) in one operation and continue if one command fails:

URL.
HTTP Method. POST

Request Payload.

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 X-NITRO-ONERROR:continue
 <!--NeedCopy-->

Payload

 {
     "ns":
     [
         {
             "name":"ns_instance1",
             "ip_address":"10.70.136.5",
             "netmask":"255.255.255.0",
             "gateway":"10.70.136.1"
         },
         {
             "name":"ns_instance2",
             "ip_address":"10.70.136.8",
             "netmask":"255.255.255.0",
             "gateway":"10.70.136.1"
         }
     ],
      "mpsuser":
     [
         {
             "name":"admin",
             "password":"admin",
             "permission":"superuser"
         },
         {
             "name":"admin",
             "password":"admin",
             "permission":"superuser"
         }
     ]
 }
 <!--NeedCopy-->

Exception Handling

The error code field indicates the status of the operation.

An error code of 0 indicates that the operation is successful.
A non-zero error code indicates an error in processing the NITRO request.

The error message field provides a brief explanation and the nature of the failure.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

REST web services

May 2, 2023

Contributed by:

S S

May 2, 2023

Contributed by:

S S

REST web services

System APIs

Configuration APIs

Create a resource

Retrieve resource details and statistics

Update a resource

Delete a resource

Bulk operations

Exception Handling

In this article