Product Documentation

REST Web Service

Dec 18, 2015

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.

Logging on to the Command Center Server

The first step towards using NITRO API is to establish a session with the server 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 for all further operations in the session.

Note: You cannot log on to the Command Center server unless you have a user account on the appliance. The configuration operations that you can perform are limited by the administrative roles assigned to your account.

To establish a session with a Command Center server with IP address 10.144.9.22 and port 8443, by using HTTPS protocol:

  • URL. https://10.144.9.22:8443/nitro/v1/login
  • HTTP Method. POST
  • Request Payload.
    { 
        "login": 
        { 
            "username":"user", 
            "password":"secret", 
            "session_timeout":3600 
        } 
    }
    
  • Response Payload.
    { 
        "errorcode": 0,  
        "message": "Done",  
        "login" :  
        { 
            "password":"", 
            "session_timeout":3600, 
            "sessionid":"70795094%3A13d1a1dee5e%3A-7f37", 
            "username":"user", 
            "remarks":"" 
        } 
    }
    
Note: The default port for HTTP is 9090 and for HTTPS is 8443.
Note: By default, the connection to the server expires after 30 minutes of inactivity. You can modify the timeout period by specifying a new timeout period (in seconds) in the login object.

To disconnect from the Command Center server, specify the session ID in the URL:

  • URL. https://10.144.9.22:8443/nitro/v1/login/70795094%3A13d1a1dee5e%3A-7f37
  • HTTP Method. DELETE
  • Response Payload.
    { 
        "errorcode": 0, 
        "message": "Done" 
    }
    

Adding Device Profiles

To discover devices on a Command Center server you must first configure a device profile that specifies the credentials and SNMP details of the device you want to discover.

To add a device profile named "my_profile1" for a NetScaler appliance.

  • URL. https://10.144.9.22:8443/nitro/v1/discovery/device_profile
  • HTTP Method. POST
  • Cookie. SESSID=70795094%3A1...
  • Request Payload.
    { 
        "device_profile": 
        { 
            "name":"my_profile1", 
            "desc":"NetScaler profile using NITRO API", 
            "device_family":"NS", 
            "prof_details": 
            { 
                "ssh_user_name":"user1", 
                ... 
                ... 
            } 
        }     
    }
    
  • Response Payload.
    { 
        "errorcode": 0,  
        "message": "Done",  
        "device_profile" :  
        [ 
            { 
                "id":7, 
                "name":"my_profile1" 
                ... 
                ... 
            } 
        ] 
    }
    

To retrieve, in a paginated manner, the details of all device profiles available on the server.

  • URL. https://10.144.9.22:8443/nitro/v1/discovery/device_profile?pageno=1&pagesize=25
  • HTTP Method. GET
  • Cookie. SESSID=70795094%3A1...
  • Response Payload.
    { 
        "errorcode": 0,  
        "message": "Done",  
        "device_profile" :  
        [ 
            { 
                "id":10, 
                "name":"ns6", 
                "desc":"new profile" 
                ... 
                ... 
            } 
        ] 
    }
    
Note: You can retrieve the details of a specific device profile by specifying the profile ID in the URL as follows: https://10.144.9.22:8443/nitro/v1/discovery/device_profile/3, where 3 is the ID of the profile.
Note: You can retrieve the count of device profiles available by using the following URL: https://10.144.9.22:8443/nitro/v1/discovery/device_profile?count=yes.

To update the details of a device profile named "my_profile1".

  • URL. https://10.144.9.22:8443/nitro/v1/discovery/device_profile
  • HTTP Method. PUT
  • Cookie. SESSID=70795094%3A1...
  • Request Payload.
    { 
        "device_profile": 
        { 
            "id":"11", 
            "name":"my_profile1", 
            "desc":"Updated description", 
            "device_family":"NS", 
            "prof_details": 
            { 
                "ssh_user_name":"user1", 
                ... 
                ... 
            } 
        }     
    }
    
  • Response Payload.
    { 
        "errorcode": 0,  
        "message": "Done",  
        "device_profile" :  
        [ 
            { 
                "id":7, 
                "name":"my_profile1" 
                ... 
                ... 
            } 
        ] 
    }
    

To delete a device profile named "my_profile1" and that has ID 11.

  • URL. https://10.144.9.22:8443/nitro/v1/discovery/device_profile/11
  • HTTP Method. DELETE
  • Cookie. SESSID=70795094%3A1...
  • Response Payload.
    { 
        "errorcode": 0,  
        "message": "Done" 
    }
    

Adding Devices

To add a device to a Command Center server you must specify the details of the device (IP address or hostname) and associate the device profile. The server automatically discovers the device by using the specified details.

To add a NetScaler appliance with IP address 10.102.29.195 by using a profile named "my_profile1".

  • URL. https://10.144.9.22:8443/nitro/v1/discovery/device_discovery_data
  • HTTP Method. POST
  • Cookie. SESSID=70795094%3A1...
  • Request Payload.
    { 
        "device_discovery_data": 
        { 
            "import_from_file":"false", 
            "ip_address_file":"", 
            "devices":"10.102.29.195", 
            "profile_name":"my_profile1" 
        } 
    }
    
  • Response Payload.
    { 
        "errorcode": 0, 
        "message": "Done", 
        "device_discovery_data" :  
        { 
            "devices":"10.102.29.195", 
            "profile_id":0, 
            "profile_name":"my_profile1", 
            "import_from_file":"false", 
            "ip_address_file":"" 
        } 
    }
    

To retrieve, in a paginated manner, the details of all devices discovered on the server.

  • URL. https://10.144.9.22:8443/nitro/v1/discovery/citrix_mo_device?pageno=1&pagesize=25
  • HTTP Method. GET
  • Cookie. SESSID=70795094%3A1...
  • Response Payload.
    { 
        "errorcode": 0,  
        "message": "Done",  
        "citrix_mo_device" :  
        [ 
            { 
                "name":"10.102.29.60", 
                "display_name":"10.102.29.60", 
    	           ..., 
                ... 
            } 
        ] 
    }
    
Note: You can retrieve the count of devices discovered by using the following URL: https://10.144.9.22:8443/nitro/v1/discovery/citrix_mo_device?count=yes.
Note: You can get the status of device discovery by specifying the device in the URL as follows: https://10.144.9.22:8443/nitro/v1/discovery/discovery_status_log/10.102.29.60?pageno=1&pagesize=25, where 10.102.29.60 is the IP address of the device.

To delete a discovered device that has IP address 10.102.29.60.

  • URL. https://10.144.9.22:8443/nitro/v1/discovery/citrix_mo_device/10.102.29.60
  • HTTP Method. DELETE
  • Cookie. SESSID=70795094%3A1...
  • Response Payload.
    { 
        "errorcode": 0,  
        "message": "Done" 
    }
    

Monitoring Services and Virtual Servers

You can monitor the services, service groups, and virtual servers across the Netscaler devices that are configured on the Command Center server.

To get the virtual servers available on discovered NetScaler appliances.

  • URL. https://10.144.9.22:8443/nitro/v1/monitoring/vserver?pageno=1&pagesize=25
  • HTTP Method. GET
  • Cookie. SESSID=70795094%3A1...
  • Response Payload.
    { 
        "errorcode": 0, 
        "message": "Done", 
        "vserver" : 
        [ 
            { 
                "view_id":-1, 
                "annotation":"Update from Periodic Poll", 
                "ns_ip":"10.102.29.60", 
                "label":"10.102.29.60", 
                "vsvr_name":"lb-vserver1", 
                ... 
                ... 
            } 
        ] 
    }
    

To get the services available on discovered NetScaler appliances.

  • URL. https://10.144.9.22:8443/nitro/v1/monitoring/services?pageno=1&pagesize=25
  • HTTP Method. GET
  • Cookie. SESSID=70795094%3A1...
  • Response Payload.
    { 
        "errorcode": 0, 
        "message": "Done", 
        "services" :  
        [ 
            { 
                "view_id":-1, 
                "annotation":"Update from Periodic Poll", 
                "ns_ip":"10.102.29.65", 
                "label":"10.102.29.65", 
                "svc_name":"nsrpcs-::1l-3008", 
                ... 
                ... 
            } 
        ] 
    }
    

To get the service groups available on discovered NetScaler appliances.

  • URL. https://10.144.9.22:8443/nitro/v1/monitoring/svcgrp?pageno=1&pagesize=25
  • HTTP Method. GET
  • Cookie. SESSID=70795094%3A1...
  • Response Payload.
    { 
        "errorcode": 0, 
        "message": "Done", 
        "svcgrp" :  
        [ 
            { 
                ... 
                ... 
            } 
        ] 
    }
    

Creating Performance Reports

The Command Center server stores performance data of the discovered devices. You can use this data to create reports that can help you analyze the performance of the devices.

To get a quick report.

  • URL. https://10.144.9.22:8443/nitro/v1/reporting/quick_report_execdata
  • HTTP Method. POST
  • Cookie. SESSID=70795094%3A1...
  • Request Payload.
    { 
        quick_report_execdata:  
        { 
            "multiple_polled_data":<Boolean_value>, 
            "device_name":<String_value>, 
            "instances":<String_value>, 
            "group_name":<String_value>, 
            "report_type":<String_value>, 
            "counter_complete_name":<String_value>, 
            "counter_name":<String_value> 
        } 
    }
    
  • Response Payload.
    { 
        "errorcode": 0, 
        "message": "Done", 
        "quick_report_execdata": 
        [ 
            { 
                "multiple_polled_data":<Boolean_value>, 
                ... 
                ... 
            } 
        ] 
    }
    

To get a custom report.

  • URL. https://10.144.9.22:8443/nitro/v1/reporting/custom_report_execdata
  • HTTP Method. POST
  • Cookie. SESSID=70795094%3A1...
  • Request Payload.
    { 
        custom_report_execdata:  
        { 
            "report_type":<String_value>, 
            "file_name_date":<String_value>, 
            "aggregate_report":<Boolean_value>, 
            "plot_bound_service":<Boolean_value>, 
            "report_datatype":<String_value>, 
            "device_names":<String_value>, 
            "custom_report_display_name":<String_value>, 
            "custom_report_name":<String_value>, 
            "instance_map":<instance_map[]_value>, 
            "graph_key":<String_value> 
        } 
    }
    
  • Response Payload.
    { 
        "errorcode": 0, 
        "message": "Done", 
        "custom_report_execdata": 
        [ 
            { 
                "report_type":<String_value>, 
                ... 
                ... 
            } 
        ] 
    }
    

Managing Device Certificates

You can manage the certificates of the devices discovered on the Command Center server.

To retrieve the certificates available on all discovered devices.

  • URL. https://10.144.9.22:8443/nitro/v1/certificate/certificate?pageno=1&pagesize=25
  • HTTP Method. GET
  • Cookie. SESSID=70795094%3A1...
  • Response Payload.
    { 
        "errorcode": 0, 
        "message": "Done", 
        "certificate" :  
        [ 
            { 
                "cert_name":"ns-server-certificate", 
                "agent":"10.102.29.65", 
                "device_type":"NetScalerVPX", 
                ... 
                ...  
            } 
        ] 
    }
Note: You can view the details of a specific certificate by using a URL as follows: https://10.144.9.22:8443/nitro/v1/certificate/certificate?filter=cert_name:ns-server-certificate,agent:10.102.29.65.

To modify the certificate polling interval to 23 hours.

  • URL. https://10.144.9.22:8443/nitro/v1/certificate/cert_polling_interval
  • HTTP Method. PUT
  • Cookie. SESSID=70795094%3A1...
  • Request Payload.
    { 
        "cert_polling_interval": 
        { 
            "polling_interval":"23" 
        } 
    }
  • Response Payload.
    { 
        "errorcode": 0, 
        "message": "Done", 
        "cert_polling_interval" :  
        { 
            "polling_interval":23 
        } 
    }

Monitoring Configuration Changes

You can monitor configuration changes across devices by using audit policies on the Command Center server. To create an audit policy you must first create an audit template.

To add an audit template.

  • URL. https://10.144.9.22:8443/nitro/v1/changemgmt/ns_template_info
  • HTTP Method. POST
  • Cookie. SESSID=70795094%3A1...
  • Request Payload.
    { 
        ns_template_info: 
        { 
            "owner":<String_value>, 
            "template_name":<String_value>, 
            "template_id":<Integer_value>, 
            "last_modified":<String_value>, 
            "template_commands":<ns_template_commands_info[]_value> 
        } 
    }
    
  • Response Payload.
    { 
        "errorcode": 0, 
        "message": "Done", 
        "ns_template_info": 
        [ 
            { 
                "owner":<String_value>, 
                ... 
                ... 
            } 
        ] 
    }
    

To retrieve the audit templates configured on the server.

  • URL. https://10.144.9.22:8443/nitro/v1/changemgmt/ns_template_info?pageno=1&pagesize=25
  • HTTP Method. GET
  • Cookie. SESSID=70795094%3A1...
  • Response Payload.
    { 
        "errorcode": 0, 
        "message": "Done", 
        "ns_template_info": 
        [ 
            { 
                "template_name":<String_value>, 
                "owner":<String_value>, 
                ... 
                ... 
            } 
        ] 
    }
    

To add an audit policy.

  • URL. https://10.144.9.22:8443/nitro/v1/changemgmt/audit_policy
  • HTTP Method. POST
  • Cookie. SESSID=70795094%3A1...
  • Request Payload.
    { 
        audit_policy: 
        { 
            "selected_templates":<String_value>, 
            "policy_name":<String_value>, 
            "running_vs_saved":<Boolean_value>, 
            "schedule_time":<String_value>, 
            "running_vs_chosen_template":<Boolean_value> 
        } 
    }
    
  • Response Payload.
    { 
        "errorcode": 0, 
        "message": "Done", 
        "audit_policy": 
        [ 
            { 
                "selected_templates":<String_value>, 
                "policy_name":<String_value>, 
                ... 
                ... 
            } 
        ] 
    }
    

To retrieve the audit policies configured on the server.

  • URL. https://10.144.9.22:8443/nitro/v1/changemgmt/audit_policy?pageno=1&pagesize=25
  • HTTP Method. GET
  • Cookie. SESSID=70795094%3A1...
  • Response Payload.
    { 
        "errorcode": 0, 
        "message": "Done", 
        "audit_policy": 
        [ 
            { 
                "policy_name":<String_value>, 
                ... 
                ... 
            } 
        ] 
    }
    

Using Tasks to Configure Managed Devices

You can configure the devices available on the Command Center server by using built-in tasks or by defining custom tasks.

To add a custom task.

  • URL. https://10.144.9.22:8443/nitro/v1/configuration/ns_task
  • HTTP Method. POST
  • Cookie. SESSID=70795094%3A1...
  • Request Payload.
    { 
        ns_task: 
        { 
            "secondary_first":<Boolean_value>, 
            "enable_rba":<Boolean_value>, 
            ... 
            ... 
        } 
    }
    
  • Response Payload.
    { 
        "errorcode": 0, 
        "message": "Done", 
        "ns_task": 
        [ 
            { 
                "secondary_first":<Boolean_value>, 
                "enable_rba":<Boolean_value>, 
                ... 
                ... 
            } 
        ] 
    }
    

To schedule a custom task.

  • URL. https://10.144.9.22:8443/nitro/v1/configuration/ns_task_execution_data
  • HTTP Method. POST
  • Cookie. SESSID=70795094%3A1...
  • Request Payload.
    { 
        ns_task_execution_data:  
        { 
            "rba_password":<String_value>, 
            "user_input_props":<Properties_value>, 
            "device_list":<String[]_value>, 
            "execute_on_secondary_first":<Boolean_value>, 
            ... 
            ... 
        } 
    }
    
  • Response Payload.
    { 
        "errorcode": 0,  
        "message": "Done",  
        "ns_task_execution_data": 
        [ 
            { 
                "rba_password":<String_value>, 
                "user_input_props":<Properties_value>, 
                "device_list":<String[]_value>, 
                "execute_on_secondary_first":<Boolean_value>, 
                ... 
                ... 
            } 
        ] 
    }
    

Migrating NetScaler Configurations

You can port the configurations from a source NetScaler appliance to target NetScaler appliances using one of the following approaches, described in this section.

  • Directly from Source to Target
  • After Editing the Configurations

Directly from Source to Target

In this approach, you specify the source NetScaler details and the details of the NetScaler to which you want to migrate the configurations.

  • URL. https://10.144.9.22:8443/nitro/v1/configuration/configuration_template
  • HTTP Method. POST
  • Cookie. SESSID=70795094%3A1...
  • Request Payload.
    { 
        "params": 
        { 
            "action":"execute" 
        }, 
        "configuration_template": 
        { 
            "name":"Rest_Execute_1", 
            "device_family":"NS", 
            "template_source":"device", 
            "source_device":"10.102.40.66", 
            "configuration_period":"Today", 
            "devices":["10.102.40.60","10.102.40.61"], 
            "config_as_file":false, 
            "auto_rollback":false, 
            "alarm_settings":true, 
            "report_as_mail":true, 
            "report_mail_id":"abc@xyz.com", 
            "critical_severity":true, 
            "major_severity":false, 
            "minor_severity":false, 
            "warning_severity":false 
        } 
    }
    

After Editing the Configurations

You must retrieve the NetScaler configurations. These configurations are saved as a text file in the <Command_Center_Home>\temp directory. Then, you can edit the configurations as required and port them to the target NetScaler appliances.

  1. Retrieve the NetScaler configurations.
    • URL. https://10.144.9.22:8443/nitro/v1/configuration/configuration_template
    • HTTP Method. POST
    • Cookie. SESSID=70795094%3A1...
    • Request Payload.
      { 
          "params": 
          { 
              "action":"save" 
          }, 
          "configuration_template": 
          { 
              "name":"Rest_Save_1", 
              "device_family":"NS", 
              "template_source":"device", 
              "source_device":"10.102.40.66", 
              "configuration_period":"Today", 
              "config_as_file":true, 
               
          } 
      }
      
  2. Edit the configurations as required.
  3. Migrate the updated configurations to the target NetScaler appliance.
    • URL. https://10.144.9.22:8443/nitro/v1/configuration/configuration_template
    • HTTP Method. POST
    • Cookie. SESSID=70795094%3A1...
    • Request Payload.
      { 
          "params": 
          { 
              "action":"load_execute" 
          }, 
          "configuration_template": 
          { 
              "name":"Rest_load_execute_1", 
              "device_family":"NS", 
              "template_source":"device", 
              "profile_file_name":"Rest_Save_1", 
              "devices":["10.102.40.60","10.102.40.61"], 
              "config_as_file":false, 
              "auto_rollback":false, 
              "alarm_settings":true, 
              "report_as_mail":true, 
              "report_mail_id":"abc@xyz.com", 
              "critical_severity":true, 
              "major_severity":false, 
              "minor_severity":false, 
              "warning_severity":false 
          } 
      }