Please complete the above form, then draft your content below following the authoring guidance at the bottom of this file.
Once you’ve completed your draft and all internal reviews, please submit your post through the Welcome tool (available in OKTA). The content team will complete an editing review, contact you with any queries, and route the final content through the legal and search optimization teams before staging and publishing.
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:
| 1 | return all appliances where (version is 5.2.1 or 5.2.2) and (model is FA–m20 or FA–x70) |
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 consider 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 easily and succinctly expressed as:
| 1 | return all appliances where FlashArray version is lower than {{min–fa–ver–supported}} or FlashBlade version is lower than {{min–fb–ver–supported}} |
The REST API also exposes an os property that makes it very convenient to identify FlashArray systems (for which os=”Purity//FA”) and FlashBlade systems (for which os=”Purity//FB”). The real filtering condition would thus be:
| 1 | return all appliances where (version is lower than {{min–fa–ver–supported}} and os=‘Purity//FA’) or (version is lower than {{min–fb–ver–supported}} and os=‘Purity//FB’) |
Take a look at the Get Appliances to Be Upgraded query and test it to see how it performs in your environment. The actual filter request parameter value is:
| 1 | (version<‘5.1.0’ and os=‘{{flasharray_os}}’) or (version<‘2.3.0’ and os=‘{{flashblade_os}}’) |
Note that the parentheses in the query above are superfluous (since the two 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:
| 1 | ?filter=name=‘{{selected_pod_name}}’ |
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):
| 1 | ?filter=on.name=‘{{selected_array_name}}’ |
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:
| 1 | ?filter=arrays[all].status=‘online’ |
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:
| 1 | ?filter=contains(name, ‘vvol-‘) and arrays[any].name=(‘{{selected_array_name}}’, ‘{{selected_array2_name}}’) |
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 (Pure1 login required) as well as the Sorting section (Pure1 login required) 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 in. The list of all available metrics is available in the Get All Metrics request (you can also specify two 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 of 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, this 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 System 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:
| 1 | ?names=(‘array_total_capacity’, ‘array_data_reduction’)&resource_ids=(‘{{selected_array_id}}’, ‘{{selected_array2_id}}’)&aggregation=‘avg’&resolution={{metric_resolution}}&start_time={{start_time}}&end_time={{end_time}} |
Read More from This Series
Exploring the Pure1® REST API – Part 1
Exploring the Pure1® REST API – Part 2
Exploring the Pure1® REST API – Part 3
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 gives you the drive and willingness to write cool code or integrations around the Pure1 REST API.
If you are a Python or PowerShell developer, we already have you covered with the Pure Python client and the Pure1 PowerShell module.
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.
The Pure Storage Platform
A platform that grows
with you, forever.
Simple. Reliable. Agile. Efficient. All as-a-service.
