Today we will be discussing the details and artefacts of Project Vision. This project leverages Postman’s import collection capabilities to provide sample API calls. It provides API examples for the following products:
- PowerMax
- XtremIO
- Unity
- PowerFlex(formerly ScaleIO and VxFlex)
- PowerStore
- PowerOne
- VPLEX – Courtesy of Ankur Patel
- ECS management and ECS S3 interface – Courtesy of Christopher Jenkins
The goal of the project is to help customers of these products to automate day 1 and day 2 operations by looking at handy examples. API reference guides can sometimes be many hundred pages long and take considerable effort to understand. So by looking at some of the most common operational examples one can kickstart coding efforts. Each collection has been built to provide sample calls in these areas:
- Gather system and hardware information
- Basic provisioning
- Performance and event collection
The following screenshot shows part of the calls provided by the PowerMax collection
With Project Vision, one can learn by example how API authentication is undertaken and how parameters or JSON bodies are passed. Additionally every API call has been provided with a sample reply so that developers can more easily see what fields are relevant for their purpose and help fast tracking the coding effort
You can access Project Vision’s Postman collections in the following GitHub repo:
https://github.com/cermegno/Project-Vision
Instructions on how to use these collections:
- Download Postman for your operating system from here
- Import the collections by clicking File > Import > Choose Files. The collection will appear in the left pane. At this point you can click on any of the calls to see the details
- The collections don’t use specific array information like IP address, password, etc. To use the collection to send calls to a real array you can create an “environment” and define that information as variables. The following screenshot shows how environment variables in Postman use the “double curly bracket” notation, ex: {{ ip }}
All collections require two variables: “ip” and “pwd“. Additionally PowerMax requires “serial” as you can see in the previous screenshot.
To create a new environment for your array, click on the little “eye” icon at the top right, next to the “environment” drop-down menu. Then click “Add”
A form like the following will appear. Populate the variables as shown, using the “current value”, not the “initial value”. Then click Add
At this point you can select the environment using the drop-down menu. Once you do it you can hover your mouse over each of the variables in your API call to see what value will be used to make the API call. See example below
The VxFlex(PowerFlex) and PowerStore collections make use of a Postman “test” to create the “token” environment variable dynamically. Run the “login” call before running any other calls. If the token expires you will need to run the “login” call again to get a fresh token
The Unity API also uses CSRF tokens to secure POST, PUT and DELETE calls. The CSRF token is provided as part of GET calls. The Unity collection has been configured with a test in the first query (named “Get FC ports – set token). Run this call before attempting any other call or after the token expires
The PowerOne collection has been developed using a simulator as I don’t have access to a real PowerOne. The simulator listens on 127.0.0.1:3000. The simulator doesn’t require login. So all the parameters have been hard-coded. The only parameter required is “token” if you want to experience the “login” functionality. However, please note this collection will not work on a real PowerOne system as it requires additional header information.
The following table summarizes the environment variables required for each collection
| Array | Variable | Variable | Variable |
|---|---|---|---|
| XtremIO | ip | pwd | |
| Unity | ip | pwd | csrfToken |
| PowerMax/VMAX | ip | pwd | serial |
| PowerFlex/ScaleIO | ip | pwd | token |
| PowerStore | ip | pwd | token |
| PowerOne simulator | token |
Every API call in Project Vision includes an example response. So even if you don’t have access to a real storage array you can see how its API behaves. To see an example response, click on the “examples” drop-down menu just under the “environment” section, and them click on the example name
Now you can scroll down to the “Example Response” section to see the recorded response
Another great feature that Postman provides us with is the ability to generate sample code for many programming languages for every call in the collection. In order to use this feature you will need to create a free account with Postman. Once you do that you can click on the little triangle next to the collection name and then “View in web”
The web documentation for the API collection will appear in your Internet browser. The right tab shows the code for the language of choice. The following screenshot shows sample code for creating a volume in VxFlex (ScaleIO) using Python’s requests library
Through this feature Postman provides coding samples in the following languages. Just use the “Search Language drop-down at the top of the right-pane:
- cURL
- C
- C#
- GO
- Java
- Javascript
- NodeJs
- Objective-C
- PHP
- Powershell
- Python
- Ruby
- Shell
- Swift
The following video shows Project Vision
{{ vExpose }}.Blog 
Hello,
Do you have the API endpoint for getting the system faults? Similar to ‘uemcli -d 1.1.1.1 /sys/res/health/fault show’?
Thank you
LikeLike
Hi Chris,
To list system alerts you can use /api/types/alert/instances REST API URI. This will list all the system alerts, which then you can filter based on the severity. Below is the link for the API reference guide. You can use this URI with the same project Vision postman collection. Do reach out in case you’ve any further queries.
https://developer.dell.com/apis/3028/versions/5.1.0/docs?nodeUri=%2Fmodels%2Fspec_publish.yml%2Fdefinitions%2Falert
LikeLike
Hi Chris,
There is no straight 1-to-1 mapping. The reason being is that the uemcli you are referring to deals both with storage resources and pools at the same time. In the REST API these are 2 separate resources so you will have to use 2 different calls
Firstly, this call gives you information about all block and file resources (excluding “pools”). You have to explicitly request the “health” parameter. You might want to request more parameters that are important to your use case. Notice how I have included also “name” and “type”. Type is necessary so that we can distinguish between volumes, files systems, vVols …. You can see all parameters available for that call in this page:
https://developer.dell.com/apis/3028/versions/5.1.0/docs?nodeUri=%2Fmodels%2Fspec_publish.yml%2Fpaths%2F~1api~1types~1storageResource~1instances%2Fget
So, this call retrieves health information for all storage resources in the system:
https://ip/api/types/storageResource/instances?fields=name,health,type
This is an extract of the output from my array. Notice how a health value of “5” maps to “OK” and a type of “1” maps to “filesystem” in the tables further below
“entries”: [
{
…
“content”: {
“id”: “res_166”,
“name”: “nfs-test01”
“type”: 1,
“health”: {
“value”: 5,
“descriptions”: [
“The component is operating normally …
Secondly, since pool resources are not included in the previous call you need to use this other call to list them. You can see all parameters available for that call in this page:
https://developer.dell.com/apis/3028/versions/5.1.0/docs?nodeUri=%2Fmodels%2Fspec_publish.yml%2Fpaths%2F~1api~1types~1pool~1instances%2Fget
So, this call retrieves health information for all pools in the system
https://ip/api/types/pool/instances?fields=name,health
This is an extract of the output from my array. Notice how a health value of 7 maps to “OK But Minor Warning” in the table further below
“entries”: [
{
…
“content”: {
“id”: “pool_6”,
“name”: “Dynamic Pool”
“health”: {
“value”: 7,
“descriptions”: [
“This storage pool has exceeded …
This is what the health score readings mean
Health Description
0 Unknown
5 OK
7 OK But Minor Warning
10 Degraded
15 Minor Issue
20 Major Issue
25 Critical Issue
30 Non Recoverable Issue
And this is what the storage resource types mean
Type Description
1 filesystem
2 consistencyGroup
3 vmwarefs
4 vmwareiscsi
8 lun
9 VVolDatastoreFS
10 VVolDatastoreISCSI
Finally you can programmatically parse the output for “entries” items whose “health value” equals the health score that interests you.
LikeLike
Hello,
Thank you for the response. I guess I should of mentioned I am specifically looking for hardware faults. I tried the URI you posted above, but it does not show hardware faults. The system I am testing against has 2 faulted disks.
Thank you
LikeLike
Hi Chris,
As in my previous response, there is no straight call for that. Most REST API’s are designed for “granular” access to resources and higher level functions are implemented by means of multiple calls.
I think you have to options:
1 – Use the events collection
This will capture all the issues, hardware and not hardware related. Try this call:
https://ip/api/types/event/instances?fields=severity,message,source
Notice how I am requesting explicitly severity and source. You can then parse the output for the sources and severities that matter to your use case.
Use this table to decode the severity:
8 OK
7 DEBUG
6 INFO
5 NOTICE
4 WARNING
3 ERROR
2 CRITICAL
1 ALERT
0 EMERGENCY
2 – Use individual hardware component API calls
There is no single API call that encompasses all the hardware components. Each component has a corresponding API object. This is the full list:
GET /api/types/battery/instances
GET /api/types/dae/instances
GET /api/types/disk/instances
GET /api/types/dpe/instances
GET /api/types/ethernetPort/instances
GET /api/types/fan/instances
GET /api/types/fcPort/instances
GET /api/types/ioModule/instances
GET /api/types/lcc/instances
GET /api/types/memoryModule/instances
GET /api/types/powerSupply/instances
GET /api/types/sasPort/instances
GET /api/types/ssc/instances
GET /api/types/ssd/instances
GET /api/types/storageProcessor/instances
All these API objects have a health score that maps as described in this table.
Health Description
0 Unknown
5 OK
7 OK But Minor Warning
10 Degraded
15 Minor Issue
20 Major Issue
25 Critical Issue
30 Non Recoverable Issue
So for example you can get health info about your disks with this call:
https://ip/api/types/disk/instances?fields=name,health
I get an output on my array like this
…
“entries”: [
{
…
“content”: {
“id”: “dpe_disk_0”,
“name”: “DPE Drive 0”,
“health”: {
“value”: 5,
“descriptions”: [
“The component is operating normally …
From here you can parse the outputs and look for health scores that matter your use case, ex: value > 5. Then use the name and description to act on the issue.
Hope it helps
LikeLike