The new NITRO API eDocs have recently been added to the growing list of online documentation made available by Citrix. As you can see from those documents, if you are using one of the NITRO SDKs (Java or C#) then creating a NITRO session on the Netscaler is as simple as creating a new “nitro_service” object, choosing your connection method and setting your credentials appropriately.

Following that guide, if have supplied valid credentials and your Netscaler is correctly configured then you can continue on your merry way and remain ignorant of what has just happened in the background. However, if you are looking to use another language to make use of the RESTful interface that NITRO provides, then you will need to know more.

As well as the eDocs, the NITRO API Documentation is available from the Netscaler GUI, of course, but again that serves as more of a functional specification than a guide to building a successful REST client in your language of choice. So, what exactly is required to take that first step and log in to a Netscaler?

The short answer is: A properly formatted POST request using appropriate credentials – easy, right?

Creating that properly formatted request, from scratch, can be more tricky than it appears. The exact requirements, along with a very basic code example, are to be found below.

First of all, let’s take a look at a snippet from the API documentation (taken from Citrix NetScaler NITRO Getting Started Guide for REST API - part of the NITRO API Documentation archive which you will find under the Download tab on your Netscaler).  That guide describes a valid login request as follows:

Request Payload:

object=
{
"login":
{
"username":"username",
"password":"secret"
}
}

That looks straight forward enough, but as always the devil is in the details. First of all, there are a few prerequisites omitted:

  1. The request must include a Content Type header of: application/x-www-form-urlencoded
  2. The “object=” string at the start of the payload is not just descriptive, it is required
  3. The remainder of the payload should be URL encoded

Unless the above criteria are met you are likely to receive an error response (probably “Invalid Post Request”) as you attempt to login.

It is easy to list the requirements, but often times a code sample is far more useful. Here is a very basic login request example using the popular Python programming language:

#import the necessary libraries
import json
import httplib2
import urllib
#set the headers and the base URL
headers = {'Content-type': 'application/x-www-form-urlencoded'}
url = 'http://192.168.100.1/nitro/v1/config/'
#contruct the payload with URL encoding
payload = {"object":{"login":{"username":"user","password":"secret"}}}
payload_encoded = urllib.urlencode(payload)
#create a HTTP object, and use it to submit a POST request
http = httplib2.Http()
response, content = http.request(url, 'POST', body=payload_encoded, headers=headers)
#for debug purposes, print out the headers and the content of the response
print json.dumps(response, sort_keys=False, indent=4)
print json.dumps(content, sort_keys=False, indent=4)

The credentials and IP address of the Netscaler will need to be adjusted in the code above to suit your environment, but otherwise running the code above should be sufficient to log into a Netscaler and receive the required Session ID. What to do next with that Session ID will be the subject of the next post.