REST Web Services

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 will identify 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.

You must specify the username 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 a 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

    pre codeblock Content-Type:application/vnd.com.citrix.sdx.login+json <!--NeedCopy-->

    Note: Content types such as ‘application/x-www-form-urlencoded’ that were supported in earlier versions of NITRO can also be used. You must make sure 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

    pre codeblock { "login": { "username":"nsroot", "password":"verysecret" } } <!--NeedCopy-->

• Response Payload

  • Header

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

Note: You must 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:

``` pre codeblock { “login”: { “username”:”nsroot”, “password”:”verysecret”, “timeout”:3600 } }

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

-  **URL**
-  **HTTP Method**
-  **Request**
    -  **Header**

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

-  **Payload**

    ``` pre codeblock
    {
        "ns":
        {
            ...
        }
    }
    <!--NeedCopy--> ```

• Response.

  • Header

    pre codeblock HTTP/1.0 201 Created <!--NeedCopy-->

To disconnect from the appliance, use the DELETE method:

• URL
• HTTP Method DELETE
• Request

  • Header

    pre codeblock 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 resources of the SDX appliance.

Each SDX resource has an 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>

Creating a Resource

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

• URL
• HTTP Method
• Request

  • Header

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

  • Payload

    pre codeblock { "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-->

Retrieving 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 on the basis of 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 a large number of 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 Citrix ADC instances on a SDX that has 53 of them. Instead of retrieving all 53 in one big response, you can configure the results to be divided into pages of 10 Citrix ADC instances each (6 pages total), and retrieve them from the server page by page.

  You specify the page count with the pagesize query string parameter and use the pageno 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 pagesize setting between requests.

  Note: If you want 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 Citrix ADC instances available, the URL would be http://<IP>/nitro/v2/config/<resource_type>?count=yes

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

• URL
• HTTP Method GET

Updating 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 Citrix ADC instance with ID 123456a to vpx2:

• URL
• HTTP Method
• Request Payload

  • Header

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

  • Payload

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

Deleting a Resource

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

• URL
• HTTP Method
• Request

  • Header

    pre codeblock 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 executed before the error are committed.
• Continue. All the commands in the list are executed even if some commands fail.

Note: You must configure the required behavior in the request header using the X-NITRO-ONERROR parameter.

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

• URL.
• HTTP Method.
• Request Payload.

  • Header

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

  • Payload

    pre codeblock { "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 (Citrix ADC and two MPS users) in one operation and continue if one command fails:

• URL.
• HTTP Method. POST
• Request Payload.

  • Header

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

  • Payload

    pre codeblock { "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 errorcode field indicates the status of the operation.

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

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