Product Documentation

REST Web Service

May 15, 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 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.

Logging on to the NetScaler Insight Center Appliance

The first step toward using NITRO is to establish a session with the NetScaler Insight Center virtual 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 cannot log on to the NetScaler Insight Center virtual appliance 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 connect to a NetScaler Insight virtual appliance with IP address 10.102.126.213 by using the HTTPS protocol:
  • URL. https://10.102.126.213/nitro/v2/config/login/
  • HTTP Method. POST
  • Request.
    • Header
      Content-Type:application/vnd.com.citrix.insight.login+json
      
      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.insight.login+json'.
    • Payload
      { 
          "login": 
          { 
              "username":"admin", 
              "password":"verysecret" 
          } 
      }
      
  • Response.
    • Header
      HTTP/1.0 201 Created 
      Set-Cookie: 
      NITRO_AUTH_TOKEN=##87305E9C51B06C848F0942; path=/nitro/v2
      
Note: You must use the session ID in all further NITRO operations on the virtual appliance.
Note: By default, the connection to the virtual 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":"admin", 
        "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 registering a NetScaler appliance:
  • URL. https://10.102.126.213/nitro/v2/config/managed_device/
  • HTTP Method. POST
  • Request.
    • Header
      X-NITRO-USER:admin 
      X-NITRO-PASS:verysecret 
      Content-Type:application/vnd.com.citrix.insight.managed_device+json
      
    • Payload
      { 
          "managed_device": 
          { 
              "ip_address":"10.102.29.60", 
              "profile_username":"admin", 
              "profile_password":"verysecret", 
              "type":"ns" 
          } 
      }
      
  • Response.
    • Header
      HTTP/1.0 201 Created
      

To disconnect from the virtual appliance, use the DELETE method:

  • URL. https://10.102.126.213/nitro/v2/config/login/
  • HTTP Method. DELETE
  • Request.
    • Header
      Cookie:NITRO_AUTH_TOKEN=tokenvalue 
      Content-Type:application/vnd.com.citrix.insight.login+json
      

Registering a NetScaler Appliance

To register a NetScaler appliance with the NetScaler Insight Center appliance, you must specify the NetScaler IP (NSIP) address, the user name, and the password of the NetScaler appliance in the managed_device object.

To register a NetScaler appliance with NSIP address 10.102.29.60:

  • URL. https://10.102.126.213/nitro/v2/config/managed_device/
  • HTTP Method. POST
  • Request.
    • Header
      Cookie:NITRO_AUTH_TOKEN=tokenvalue 
      Content-Type:application/vnd.com.citrix.insight.managed_device+json
      
    • Payload
      { 
          "managed_device": 
          { 
              "ip_address":"10.102.29.60", 
              "profile_username":"admin", 
              "profile_password":"verysecret", 
              "type":"ns" 
          } 
      }
      

To retrieve a list of NetScaler appliances configured on an Insight appliance:

  • URL. http://10.102.126.213/nitro/v2/config/managed_device/
  • HTTP Method. GET
  • Request.
    • Header
      Cookie:NITRO_AUTH_TOKEN=tokenvalue
      

Among other parameters, the response payload provides an identity for each NetScaler appliance. You must use this ID to identify a NetScaler in further operations.

Updating NetScaler Appliance's Login Credentials

If the login credentials of a NetScaler appliance are updated after it is registered to a NetScaler Insight Center appliance, they have to be updated on the Insight appliance.

To update the password of a NetScaler appliance with IP address 10.102.29.60:

  • URL. https://10.102.126.213/nitro/v2/config/device_profile/
  • HTTP Method. PUT
  • Request.
    • Header
      Cookie:NITRO_AUTH_TOKEN=tokenvalue 
      Content-Type:application/vnd.com.citrix.insight.device_profile+json
      
    • Payload
      { 
          "device_profile": 
          { 
              "username":"admin", 
              "password":"verysecret-new", 
              "id":"507be920475294e414f90889" 
          } 
      }
      
      Note: The ID of the NetScaler appliance must be obtained by using the GET HTTP method on the http://10.102.126.213/nitro/v2/config/managed_device/ URL.

Gathering Performance Data about an Application

To gather performance data from an appliance, you must select the virtual server, specify the filter condition, and then enable Appflow on the appliance in the ns_vserver_appflow_config object. The appliance then starts gathering performance data for the applications (services) bound to the virtual server.

Note: This operation gathers the performance data but does not display.

To gather performance data of an application linked to virtual server with name "http_test":

  • URL. http://10.102.126.213/nitro/v2/config/ns_vserver_appflow_config/
  • HTTP Method. PUT
  • Request.
    • Header
      Cookie:NITRO_AUTH_TOKEN=tokenvalue 
      Content-Type:application/vnd.com.citrix.insight.ns_vserver_appflow_config+json
      
    • Payload
      { 
          "ns_vserver_appflow_config": 
          { 
              "appflow_policy_rule":"TRUE", 
              "appflowlog":"enabled", 
              "es4nslog":"enabled", 
              "name":"http_test", 
              "state":"UP", 
              "ns_ip_address":"10.102.29.60", 
              "ip_address":"10.102.126.237", 
              "type":"lb", 
              "servicetype":"HTTP" 
          } 
      }
      

Generating Performance Reports

To generate a report of the performance data of an application (a virtual server), you must specify the period for which you want the data in the URL.

To generate a report of the performance data for a device with IP address 10.102.71.201, for the past one month:
  • URL. http://10.102.60.45/nitro/v2/appflow/user_agent?args=device_ip_address:10.102.71.201&asc=no&order_by=total_requests&pagesize=25&type=total_requests&duration=last_1_month
    where,
    • asc=no: Displays records in descending order.
    • order_by=total_requests: Orders records on the basis of the total requests.
    • pagesize=25: Displays 25 records per page.
    • type=total_requests: Total requests to be displayed.
    • duration=last_1_month: Records of the last one month must be displayed.
  • HTTP Method. GET
  • Response Payload.
    { 
        "errorcode": 0,  
        "message": "Done",  
        "user_agent":  
        [  
            {  
                "__count": "-1",  
                "http_resp_status_name": "",  
                "server_ip_address": "",  
                "name": "Chrome",  
                "http_req_method_name": "",  
                "rpt_sample_time": "-1",  
                "total_bytes": "16644969",  
                "device_ip_address": "10.102.71.201",  
                "uri_url": "",  
                "max_transaction_time": "-1",  
                "app_unit_name": "",  
                "render_time": "14",  
                "client_ip_address": "",  
                "id": "",  
                "app_unit_ip_address": "",  
                "total_requests": "245",  
                "operating_system_name": "" 
            }, 
            {  
                "__count": "-1",  
                "http_resp_status_name": "",  
                "server_ip_address": "",  
                "name": "Unknown",  
                ... 
                ... 
            } 
        ] 
    }
    

Exception Handling

The response header provides the status of an operation by using HTTP status codes and the response payload provides the requested resource object (for GET method) and error details (for unsuccessful operation). NITRO does not provide a response payload for successful POST, PUT and DELETE methods. For successful GET method, the response payload consists only the requested resource object.

For a more detailed description of the error codes, see the API reference available in the <NITRO_SDK_HOME>/doc folder.