Using the XtremIO REST API - Part 2

In Part 1 of Using the XtremIO REST API I covered how to access the API, and how to read data from it. This time I'm going to cover how to make changes.

REST is based on HTTP, and whilst there's really only one "command" for reading data ("GET"), there 3 main ones for making changes - "POST", "PUT" and "DELETE".

Lets start with what is the easiest - although probably most dangerous - one of the three. DELETE.

Deleting

When accessing an item via the REST API we saw that each item has a unique URL. For example, we were able to access details of a specific volume by doing a GET request to it's URL like this :

[scott ~]$ curl -u showard:Xtrem10 -k -s https://xms/api/json/v2/types/volumes/4

or even by specifically including it's volume name, such as :

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

Note that we haven't specifically stated that we want to do a GET request, but this is what curl does by default.

To delete a volume, we simply change the method that we're using from the default of GET to DELETE and then pass the URL of whatever item we want to delete in exactly the same way we did above. For curl, the method is specified using the -X option, so to delete a volume we simply do :

[scott ~]$ curl -X DELETE -u showard:Xtrem10 -k -s https://xms/api/json/v2/types/volumes/9182
[scott ~]$

or to delete by name :

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

Note that when it's successful, this command simply returns with no error but no other output. If you try and delete something that doesn't exist (or that you've already deleted!) then it'll return an error :

[scott ~]$ curl -X DELETE -u showard:Xtrem10 -k -s https://xms/api/json/v2/types/volumes/9182
{
    "message": "obj_not_found",
    "error_code": 400
}

Creating

Creating an object is only slightly more difficult than deleting one. The confusion with creating usually comes down to the distinction between the POST and PUT methods. These two sound similar and often do similar things - but they are different.

The easiest way to think of it is that POST is used when creating something NEW, whereas PUT is used when modifying an existing object. So for example, if we want to create a new volume, we would use POST. If we want to modify a detail on an existing volume (change its name, etc) then we would use PUT.

Both POST and PUT require the details of what you're asking for to be included in the 'body' of the request, and to be formatted in JSON. Thankfully the requests, and thus the JSON formatting, are normally relatively small and simple.

For example, lets say that we want to create a new volume called "NewVol", which is 1TB in size. as we're creating something new, we obviously need to do a POST request. The URL that we send the request to is that of whatever we want to create - in this case that's a volume, so it's going to be a POST to /api/json/v2/types/volumes

Thus we're looking at something like this :

[scott ~]$ curl -X POST -u showard:Xtrem10 -k -s https://xms/api/json/v2/tyes/volumes
{
    "message": "Invalid request",
    "error_code": 400
}

But as you can see that gave an error - because we didn't actually specify what we wanted to create!

In order to know what argument pass, the best place to look is the XtremIO REST API guide. Doing that, we see that the manditory fields for creating a new volume are the Volume Name ("vol-name") and the Size ("vol-size").

Turning these options into JSON format, we get something like :
{"vol-name":"MyVol","vol-size":"1T"}

As you can see, the JSON side of things is actually fairly simple - just put quotes around everything that is a string, put colons between names and their values, commas between the different value-pairs, and then surround the whole thing in {}'s

In order to pass this as the "body" of the post using curl we need to use the -d option, and then include what we want in the body in 'single quotes'. eg :

[scott ~]$ curl -X POST -d '{"vol-name":"MyVol","vol-size":"1T"}' -u showard:Xtrem10 -k -s https://xms/api/json/v2/types/volumes
{
    "links": [
        {
            "href": "https://xms/api/json/v2/types/volumes/19",
            "rel": "self"
        }
    ]
}

The return from the command, indicating a successful operation, is a JSON blob containing a URL to the newly created volume.

Modify

As covered above, PUT is used when modifying a volume. Other than the method, the only real difference when modify something is that you specify the actual item you want to modify (eg, .../volumes/1234) rather than the type as used when creating a new object (eg, .../volumes). Again the XtremIO REST API guide is the place to look for the valid options to pass in the JSON-formatted body.

eg, Lets say we wanted to rename the volume we created above. From the output when we created it we have it's URL, so we can just do :

[scott ~]$ curl -X PUT -d '{"vol-name":"MyDifferentVol"}' -u showard:Xtrem10 -k -s https://xms/api/json/v2/types/volumes/19

LUN Mapping

At first thought you might expect LUN mapping to be a a function of the volume, but it's not. Instead LUN Mapping is a separate concept that pairs a volume and an initiator group together to form a mapping. Mapping to multiple initiators means multiple distinct LUN mappings.

Checking the XtremIO REST API Guide we can see that in order to make a new LUN mapping we need to do a POST to /api/json/v2/types/lun-maps, passing a vol-id and an ig-id.

Note that in this case we need actual ID's, not the URLs. When using ID's we can generally pass one of two things - either the name of the item (in "quotes"), or the numeric ID of the item (NOT in quotes!).

Using the volume we created above as an example, the resulting URL was https://xms/api/json/v2/types/volumes/19, which means that the vol-id for this volume is 19. We could have also got that by doing a GET request for the volume (using either the URL or it's volume name) and looking at the vol-id field.

Lets say we need to make this to initiator group with ig-id 2, then we simply do :

[scott ~]$ curl -X POST -d '{"vol-id":19,"ig-id":2}' -u showard:Xtrem10 -k -s https://xms/api/json/v2/types/lun-maps
{
    "links": [
        {
            "href": "https://xms/api/json/v2/types/lun-maps/67",
            "rel": "self"
        }
    ]
}

Note that as we're using the numeric ID it's not in quotes. We could have just as well used the name of the volume, so in order to map this same volume - this time using it's name - to the initiator group called "Server1" we could use :

[scott ~]$ curl -X POST -d '{"vol-id":"MyDifferentVol","ig-id":"Server1"}' -u showard:Xtrem10 -k -s https://xms/api/json/v2/types/lun-maps

As we're using names for both options, they are in quotes.

Next up, Part 3 - Snapshots