2 min read

Using the XtremIO REST API - Part 4

In Part 1 of Using the XtremIO REST API I covered how to access the API, and how to read data from it. Part 2 covered how to create and modify objects and Part 3 covered Snapshots. Now for some Best Practices.

Best Practices

Always pass a Cluster Name.
XtremIO supports having a single XMS managing multiple separate arrays. When making API calls, the "cluster-id" or "cluster-name" options are used to specify which array the command is for.

If an XMS is currently only managing a single array then these options are optional - but it's always a good idea to include as otherwise if a second array is added any commands not specifying a cluster will fail.

Whilst it's possible to use either a cluster ID or name, you should always use the cluster-name option as the cluster-id for a specific cluster can change over time (eg, during XMS maintenance).

[scott ~]$ curl -u admin:Xtrem10 -k -s https://xms/api/json/v2/types/volumes?cluster-name=xtremio4

Some operations allows for the cluster-id/name to be passed as an option in the JSON rather than in the URL - however this doesn't apply for all requests, especially as GET requests never have a body. For consistency, I'd suggest always specifying the name in the URL as shown above.

Always check for errors.
As with any REST API, success or failure of each call is determined using the HTTP response code. It's critical to always check the response code to make sure that it is in the 200 range (ie, anything from 200 to 299, which indicate success). Anything else will indicate an error, either with the syntax of the request/body, or with the action that is being requested.

If an error does occur on the array then a JSON-formatted error string will be returned in the body of the response. For example, attempt to take an action against a volume that doesn't exist returns :

{ "message": "obj_not_found", "error_code": 400 }

Don't use CURL
Although I've used CURL for most of the examples here, it's not the right tool to use for any form of automation. If nothing else, checking for errors as mentioned above is difficult with CURL - let alone trying to parse the response be it valid or an error.

CURL makes a great learning tool (although I prefer HTTPRequester for Firefox), but for any real usage it's far better to use a real scripting language like Python, Perl, Ruby, PHP, Java, Node.js, etc...

Next up, Part 5 - Perl