DellEMC

Postman Collections for DellEMC Platforms

 

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:

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

9 replies »

  1. 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

    Like

    • 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

      Like

    • 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.

      Like

  2. 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

    Like

    • 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

      Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s