Article

Getting Started with REST APIs on XtremIO

When I was a storage admin and I wanted to extract some info from a watertight management app using good ‘ole SQL queries, I was basically S-O-L. Then along came these REST APIs and the vendors said “Oh yeah, just use REST…It’s all there.” I had no clue where to start and the documentation they provided was pathetic. So, as I didn’t have much time to dedicate to it, I threw in the towel. Fast forward four years, these REST APIs are really taking off. So much so that EMC is even leaving XtremIO’s CLI by the wayside in the current version of XIOS (4.x) in favor of REST.

The interesting thing that I’m seeing happen now is that companies are replacing their feature-rich EMC Symmetrix arrays with XtremIO. Now, the XtremIO arrays are fast and the dedupe is great, but it’s a new platform that doesn’t have the years of development and integration that the Symmetrix has, specifically with the CLI and scripting abilities. Lots of these dedicated EMC shops script clones or BCV-mirrors to run their backups or DR testing and are trading in these huge Symm frames for a half-rack of XtremIO bricks. Then they are stuck trying to figure out: How the heck are we going to script our backups now?

Fortunately, I’ve finally done the homework and can pass on what I’ve learned to you. First I’ll have to explain how REST works, then I can get into how to execute gets and posts with XtremIO.

The easiest way I can describe REST is that it’s a standard for transferring data to and from a web server by means of http using “puts” and “gets”. You create a URL which points to a web server that responds to four commands. These commands either place or pull data to or from the web server. For example, say I wanted to grab all of the consistency groups from the XtremIO cluster, the URL I’d use for the GET command is: https://XIO-XMS/api/json/v2/types/consistency-groups. The utility I’d use for the request (not a web browser) would get the data from this URL and format it in XML for me to use and manipulate.

There are a bunch of utilities out there that will perform the http operations and handle the data, but the most common that is installed on basically every linux distribution by default, is Curl. Curl is perfect for scripting because it is command line driven, lightweight and easy to use.

You’re probably asking yourself “why can’t I just use a web browser if it’s http?” Well, REST uses more than just a URL to transfer information. REST uses http headers to pass along specific parameters so we can execute commands like we would via a CLI. For example, I want to create a consistency group called “CG1” and I’d like to put a volume named “ESX_Vol_1” in it. I’d put together a curl command that looks like this:


# Curl -X POST -d ‘
{“cluster-id”:1,”consistency-group-name”:”CG1″,”vol-list”:”[ESX_Vol_1]”}’ -u admin:Xtrem10 -s https://XIO-XMS/api/json/v2/types/consistency-groups

Let’s walk through the components of this command. The -X option specifies the command type. EMC tends to use POST, PUT, DELETE, and GET. The -d option specifies the data to send to the server in the same way that a web page does with a form. In this case we put the command in single quotes, then specify the cluster ID, the consistency group name, and the list of volumes to put in the group. The -u option specifies the basic authentication username and password, separated with a colon. The -s specifies that we use silent mode, which prevents any progress outputs or error messages. Finally, we specify the URL of the management server along with the path to the API. The API path will always be “/api/json/v2/types”. If you were to run a GET request on https://XIO-XMS/api/json/v2/types, curl would output every possible manageable object of the XtremIO, and there is a ton. You’ll be amazed at the information you can pull and the objects you can manage.

Unfortunately, this article doesn’t even begin to scratch the surface on the power of these REST APIs for XtremIO. But, at least it will get you started down the right path and you can start pulling some data. I should have some more in-depth commands and procedures published on my personal blog soon that should help out those of you who are looking to replace your Symcli scripts, so stay tuned.

AHEAD Lab and Briefing Center