Exploring the Pure1® REST API – Part 3

This is Part 3 of the Pure1 REST API blog series. We recommend you read Part 1 and Part 2 first if you haven’t done so yet.

Filtering

The Pure1® UI allows you to easily filter the data you want to look at, typically as ‘or’ filters on the same property and ‘and’ filters across properties. For instance, the following visual filter:

can be logically translated to:

However, if you have a fleet of both FlashArray and FlashBlade appliances, how do you retrieve the list of appliances you wish to upgrade? You could select all the versions that you deem no longer compliant with your internal policies, as well as all the appliance models that you own. That would work, but if you’d like a single query that reliably and consistently works no matter which models you own or which FlashArray™ or FlashBlade™ versions you considered supportable by your organization, the REST API is surely your friend.

Pure1 REST API to the rescue!

Not only is the REST API able to interpret ‘lower than’ and ’greater than’ conditions, but it can also mix and match and/or conditions with specific priority. The query could be as easily and succinctly expressed as:

The REST API also exposes an ‘os’ property that makes it very convenient to identify FlashArrays (for which os=”Purity//FA”) and FlashBlades (for which os=”Purity//FB”). The real filtering condition would thus be:

Take a look at the Get Appliances To Be Upgraded query and test it in your environment to see how it performs in your environment. The actual ‘filter’ request parameter value is:

Note that the parentheses in the query above are superfluous (since the 2 ‘and’ conditions would be evaluated before the ‘or’ condition) and are only present here for legibility purposes.

Most Pure1 API endpoints support the ‘filter’ parameter and you can filter on pretty much any property that is returned in the results (some property searches might be faster than others, depending on whether they are indexed or not). Check out the Get Pod by Name request for an example:

You can also use dot notation in case the API response contains nested JSON objects. For instance, the Get Filtered Volume Snapshots returns all the volumes snapshots located on a specific appliance (represented by the ‘on’ nested JSON object):

For nested JSON array objects, you can also use the object[any] or object[all] notation, depending on your specific request. For instance, the Get Pods with all arrays online query uses the following filter:

In contrast, the Get VVol Volumes Filtered by Array request uses the [any] filter, as it seeks to retrieve the VVol volumes located at least on the arrays specified in the filter:

Note that the filter above also leverages the ‘contains’ keyword and allows filtering by more than one single array thanks to the use of parentheses.

If you want to know more, refer to the Filtering section as well the Sorting section of the official documentation.

Last but not least, let’s now turn our attention to the Metrics History endpoint (/metrics/history).

The Metrics History endpoint

The Metrics History endpoint is a bit special and requires a few mandatory parameters to return any result:

• The ‘names’ parameter: this is the name of the metric you are interested into. The list of all available metrics are available in the Get All Metrics request (you can also specify 2 or more metrics with the use of parentheses, see this request example)
• The ‘resource_ids’ or ‘resource_names’ parameter: this represents the id or name of the resource for which you wish to retrieve the metric. Check out the Get Data Reduction by Array ID and Get Data Reduction by Array Name requests as examples on how to use them.
• The ‘start_time’ and ‘end_time’ parameters represent the boundaries of the metrics history request (values should be Unix Epoch times, in milliseconds)
• The ‘resolution’ parameter: measured in milliseconds, that parameter represents how staggered you would like the metrics measurements. Note that all metrics don’t have the same minimal resolution (so you might receive a ‘resolution is too fine’ error).
• The ‘aggregation’ parameter: specifies whether you want results to be averages (assign ‘avg’ as the parameter value) or maxima (specify ‘max’ as the parameter value) in the resolution timeframe you picked.

Once these parameters are properly set, you can query Array Metrics, File Systems Metrics, Pod Metrics and Volume Metrics. All the metrics history responses have a similar format, highlighted in the screenshot below:

Specifically, the first element of the ‘data’ array is the time at which the measurement was computed, while the second element is the measurement value (in this case, the data reduction ratio).

If you would like to retrieve multiple metrics for multiple resources, we recommend doing so in one single request by leveraging the array filtering capabilities available with the names and resource_ids parameters, as highlighted in the Get Data Reduction and Total Capacity request:

Conclusion

There is a lot more you can glean by looking at the Pure1 REST API Postman collection, but I hope this not-so-short intro gave you the drive and willingness to write cool products or integrations around the Pure1 REST API.

If you are a Python, PowerShell or Go developer, we already have you covered with the Pure Python client, the Pure1 PowerShell module and the Pure Storage Go library.

If you’re interested in developing your own Pure1 REST client or if you have any questions on how best to integrate the Pure1 REST API into your application, don’t hesitate to reach out to the Pure developer community in the Pure/Code() Slack network (or join it to become a member), we’ll be happy to help you out!