Using the XtremIO REST API - Part 1

XtremIO provides an extremely good “REST API” for automating configuration of the array, but the concept of a REST API (or even any type of API!) scares a lot of people as it’s something they’ve never used before – but it shouldn’t! There is certainly a small amount of learning required, but generally it takes very little effort to familiarize yourself with the way the XtremIO REST API works.

Normally you would access the API using some form of programming/scripting language, such as Python or Perl. However for the purposes of learning or testing concepts there are a number of tools that work better, such as HTTPRrequester and curl.

Curl

Curl is a command-line tool that exists in all Linux distributions, and is available for most other Unix OSes as well as Windows. It’s what I’m going to use for the examples below simply because it’s easier to show the output than for HTTPRequester.

To use curl to access XtremIO you’ll need to pass it a few options, such as the username/password to access the array (any valid account on the XtremIO XMS will work), the URL of the API, and potentially a few options such as -k to tell curl not to validate the SSL certificate (presuming you don’t have a valid certificate installed), and -s (silent) to stop curl displaying it’s progress as it downloads the response.
A typical command to access the base of the REST API interface would thus be :
[scott ~]$ curl -u showard:Xtrem10 -k -s https://xms/api/json/v2/types

Note that I do NOT recommend using curl for actually writing scripts against any API – it’s a good testing tool, but there are far better ways to do things programmatically.

HTTPRequester

HTTPRequester is a browser extension that is available for both Chrome and Firefox. After installing it and starting it you’ll get a window that looks something like this :

As with for curl, you’ll need to provide a username/password, which is done by clicking on the “Authentication…” box, which adds two boxes below the URL for the username and the password. Also like curl you may have issues if your XMS doesn’t have a valid SSL certificate. To work around this, access any HTTPS URL on the XMS from your normal browser window (ie, not in HTTPRequester) and accept the SSL certificate error – if you don’t do this this HTTPRequester will fail silently when you try and access anything.

The RESP API

The XtremIO REST API takes on a tree structure. At the top is the base API URL, which for the current version of the API is https://xms.domain.com/api/json/v2/types where “xms.domain.com” is either the hostname or IP address of your XMS.

The response from accessing the API is always a JSON-formatted document. Whilst the JSON format may take a little getting used to, the good news is that most programming languages have modules that will parse it for you. Accessing the base URL of the API will give you a list of all of the other objects that you can access via the API. Eg :

{
    "children": [
        {
            "href": "https://xms/api/json/v2/types/alert-definitions",
            "name": "alert-definitions"
        },
        {
            "href": "https://xms/api/json/v2/types/alerts",
            "name": "alerts"
        },
[...etc...]

This is telling us that if we want to access details on “alert definitions”, then we can do this via the URL “https://xms/api/json/v2/types/alert-definitions”. Of course, alert definitions aren’t generally all that interesting, but further down in the list we’ll find some more interesting entries like volumes :

        {
            "href": "https://xms/api/json/v2/types/volumes",
            "name": "volumes"
        },

If we make a request to the URL it’s given for volumes, then not surprisingly what we get back is a list of all of the volumes (including snapshots!) that exist on the array, along with a URL for each of those volumes :

[scott ~]$ curl -u showard:Xtrem10 -k -s https://xms/api/json/v2/types/volumes
{
    "volumes": [
        {
            "href": "https://xms/api/json/v2/types/volumes/2",
            "name": "OracleProd1-Data1"
        },
        {
            "href": "https://xms/api/json/v2/types/volumes/4",
            "name": "OracleProd1-Data3"
        },
[..etc..]

Notice that at each step the base of the URL is the same, but an additional path is being added – first we added “/volumes”, then we added the volume reference number such as “/4”

If we continue to walk down the tree, we will get the full details of the volume. There is a LOT of information at this level so check it out yourself to see the full details - you’ll see the obvious things like the name of the volume (along with its unique internal “guid”) and its size :

        "vol-id": [
            "3928606e91f646478c9e95675d617190",
            "OracleProd1-Data3",
            4
        ],
        "vol-size": "262144000",

But you’ll also see details like any snapshots that have been taken from this volume, what initiators it’s mapped to, the current read and write IOPS it’s doing, and plenty more. The full list of what fields are included and what they represent can be found in the XtremIO API Guide (available on https://support.emc.com)

The same process can be followed anywhere down the tree, to find details on basically all parts of the system – from volume and snapshots, all the way to the status of the physical components of the array and any alerts and events.

Searching

Rather than having to walk down the API tree, sometimes it’s easier to be able to search at a specific level. There’s two way to do this – selecting a specific entry by name or some other ID, or “filtering” which allows searching of most fields to find objects that match your criteria.

For example, above we looked at the details of a specific volume by using its volume number (eg, “4”), but frequently it’s more convenient to access the same details via the name of the volume. In this case, we can pass a “name” option containing the name of the volume and get the same result. Eg :

[scott ~]$ curl -u showard:Xtrem10 -k -s https://xms/api/json/v2/types/volumes?name=OracleProd1-Data3

This will return the same data as if we had requested the URL https://xms/api/json/v2/types/volumes/4, but without us having to lookup the volume number first.

Filtering takes this a step further, and allows returning zero or more objects that match a specific filter criteria. Note that in this case what is returned is a list of the objects (along with their URL), not the content of the object as when using the ?name= format above.

From viewing the detail of the volume above we saw that the output included and entry :
"vol-size": "262144000",

Using that field name and value, we can filter for all volumes on the array that have a size of 262144000KB using a query like :

[scott ~]$ curl -u showard:Xtrem10 -k -s https://xms/api/json/v2/types/volumes?filter=vol-size:eq:262144000

The base URL is that for …/volumes, which would normally return a list of all volumes, but we’re applying a filter to only return those where the “vol-size” entry is “eq”ual to “262144000”. If we wanted all volumes that were NOT that size, we could have instead used the operator “ne” for not equal.

At this point I would suggest firing up HTTPRequester and walking through parts of the API tree to see the types of data you get back. Look at what volumes you have configured and what details are available for each of them. Look at your LUN mappings (/lun-maps), and then filter them to find only those relevant for a specific volume or initiator group. Work out the serial numbers of the power supplies in your Storage Controllers (I’m not sure why you’d ever need to find that programmatically, but it shows how much information is available via the API!). Perhaps check what compression ratio you’re getting on the array (hint: that’s a function of the “cluster”), or how much endurance is remaining on your SSDs.

Storage controller (XEnv) CPU utilization in HTTPRequester :

Next up, Part 2 - Creating and Modifying objects