EMC Isilon OneFS REST API using C# .NET

Introduction

This article provides a quick introduction into using the Isilon OneFS 7.2 REST API using C# .NET.

Background

I am working on several automation and visualization applications for EMC's Isilon scale out NAS platform and couldn't find much information about how to access the API in .NET. While some of the concepts in this article are pretty basic, they can be used as a starting point to get up and running quickly using the Isilon REST API. This is by all means not a complete implementation of the API, only a brief overview. To use the methods and code below, you will either need a physical Isilon cluster, or you can perform testing against a OneFS simulator (Virtual Isilon Cluster) which can be found on http://www.emc.com/products-solutions/trial-software-download/isilon.htm?PID=SWD_isilon_trialsoftware. The environment that I used to create this project consisted of a virtual Isilon cluster running on VMware Workstation.

API Workflow

The main components of the API are Authentication/Authorization which determine if the user credientials provided are valid, and are authorized to use the API. The two sub-components are the Platform and Namespace sections. The Platform section provides access to view and modify the configuration of the cluster, and the Namespace section provides access to the filesystem and files on the cluster, depending on your access level. Note: If you are going to use the API to make configuration changes on the cluster, it is highly recommended that you send all requests to a single node to avoid configuration collisions.

Basic Authentication

There are two ways you can authenticate to the API. First is by using Basic authentication, which means you must include the credentials in an HTTP header for each request. Each request will have to be authenticated against the cluster, which incurs some overhead. The following code example shows how to perform Basic authentication:

string IsilonServerAddress = "https://10.20.30.160:8080";
string ResourceString = "/platform/1/dedupe/dedupe-summary";
string UserName = "*username*";
string Password = "*password*";

// Create a web request object pointing to the Isilon server and Resource String
HttpWebRequest request = (HttpWebRequest)WebRequest.Create(IsilonServerAddress + ResourceString);

// Add the Authroization header for Basic authentication
request.Headers.Add("Authorization", "Basic " + Convert.ToBase64String(new ASCIIEncoding().GetBytes(UserName + ":" + Password)));

HttpWebResponse response = (HttpWebResponse)request.GetResponse();

The code creates an HTTP Web Request object and specifies the IP address of the cluster node. It also specifies the resource to obtain, in this case /platform/1/dedupe/dedupe-summary, which is part of the Platform section. This API call will retrieve a response that contains deduplication statistics about the cluster.

What comes back is a page that contains the requested data in JavaScript Object Notation (JSON), which looks like this:

{
"summary" : 
{
"block_size" : 8192,
"estimated_physical_blocks" : 0.0,
"estimated_saved_blocks" : 0.0,
"logical_blocks" : 0.0,
"saved_logical_blocks" : 0.0,
"total_blocks" : 18609648,
"used_blocks" : 1406655.0
}
}

Session Authentication

The second way to authenticate against the Isilon API is to use Session cookies. In this method, we instead use an HTTP POST command to pass a JSON authentication object to the Isilon API. The reponse from the cluster will contain, among other things, a session cookie that can be used to access resources on the cluster for a period of time. It also specifies how long this cookie is valid for.

// Create a web request object pointing to the Isilon server and Resource String
HttpWebRequest request = (HttpWebRequest)WebRequest.Create(IsilonServerAddress + ResourceString);
request.Method = "POST";
request.ContentType = "application/json";

// Build the JSON authentication request object
StringBuilder builder = new StringBuilder();
builder.Append("{\r\n");
builder.Append("\"username\": \"" + UserName + "\", \r\n");
builder.Append("\"password\": \"" + Password + "\",\r\n");
builder.Append("\"services\": [\"platform\"] \r\n");
builder.Append("}");

// Write the authentication request object to the request stream
StreamWriter writer = new StreamWriter(request.GetRequestStream());
writer.Write(builder.ToString());
writer.Flush();
writer.Close();

HttpWebResponse response = (HttpWebResponse)request.GetResponse();

// If successful, Isilon will set a Set-Cookie header on the response, which is our cookie
string cookie = response.Headers["Set-Cookie"];
response.Close();

Now that we have our cookie, we can use it to request the same deduplication statistics as we did in the previous example. This time we will put the cookie on the request stream to authenticate the request against the cluster. The response will be the same JSON object returned in the previous example.

// Request the dedupe-summary
ResourceString = "/platform/1/dedupe/dedupe-summary";

// Create a web request object pointing to the Isilon server and Resource String
request = (HttpWebRequest)WebRequest.Create(IsilonServerAddress + ResourceString);

// Set the cookie we received onto the request object
request.Headers.Add("Cookie", cookie);

response = (HttpWebResponse)request.GetResponse();

JSON Serialization

Now that we have successfully connected, authenticated, and can request resources from the cluster, the next step is to serialize data into .NET objects that we can use in an application. The above example returns an object of type Summary, which detailed information can be found on in the API reference document provided by EMC. Here are the properties of that object:

To serialize the return into a .NET object, we need to define a .NET class with the approporiate data contract definitions.

[DataContract]
public class DeduplicationStats
{
    [DataMember(Name = "block_size")]
    public int BlockSize;

    [DataMember(Name = "estimated_physical_blocks")]
    public int EstimatedPhysicalBlocks;

    [DataMember(Name = "estimated_saved_blocks")]
    public int EstimatedSavedBlocks;

    [DataMember(Name = "logical_blocks")]
    public int LogicalBlocks;

    [DataMember(Name = "saved_logical_blocks")]
    public int SavedLogicalBlocks;

    [DataMember(Name = "total_blocks")]
    public int TotalBlocks;

    [DataMember(Name = "used_blocks")]
    public int UsedBlocks;
}

We need one more class definition because the object that is returned from the cluster is wrapped into a blank object. So we create a generic object (IsilonReturn) that contains the DeduplicationStats object defined above.

[DataContract]
public class IsilonResponse
{
    [DataMember(Name = "summary")]
    public DeduplicationStats DedupeStats;
}

Now we can use the DataContractJsonSerializer object that is a part of the System.Runtime.Serialization.Json namespace to serialize the JSON object into the IsilonResponse object. Once the following code completes, you can access the object to get cluster deduplication statistics.

DataContractJsonSerializer js = new DataContractJsonSerializer(typeof(IsilonResponse));
IsilonResponse stats = (IsilonResponse)js.ReadObject(response.GetResponseStream());

Conclusion

This is a simple example on how you can use C# and the .NET framework to connect to an Isilon cluster and run basic commands against it. The API is full of features from both a configuration and file system access standpoint. You can use the API to perform auditing, configure protocol, job, pool, quota, and snapshot settings amongst other configuration tasks, as well as directory and file level operations.

Hope you found this information useful!

History

Jan-2015: First Version