A Beginners Guide to REST API Calls With PowerFlex

I recently received a request from the Account Team of one of our major global OEM PowerFlex customers. They were looking for help with integrating PowerFlex into the bespoke Management Systems that the customer uses. Unsurprisingly, this Management System is vendor neutral and so it is fully reliant on issuing RESTful calls out to the various storage systems that are deployed across multiple datacentres. The customer supplied a list of metrics that they use across their entire storage estate via Restful API calls. The ask was simple – could someone provide them with a list of the correct REST calls that need to be issued against a PowerFlex system in order to obtain the desired metrics?

Faced with such a request, it would have been all too easy to simply point the customer in the direction of the “PowerFlex REST API Guide” documentation, ask them to read it, wish them well and then consider it “job done”. However, it must be acknowledged that while the REST API Guide does a very thorough job of listing all of the available api call endpoints, it does suffer due to a lack of “Sample Outputs”. This means that quite often, customers who are coming to this subject without any previous knowledge of issuing REST calls to PowerFlex can find it hard to know where to start.

One other point worth mentioning is that since VxFlex OS 3.0 was released, the number of API calls available to users has increased significantly, both in terms of scope and detail. It is now possible to retrieve detailed metrics around IOPS and latencies that were simply not there in the previous 2.x call library, plus major PowerFlex features that have been added over the past 18 months, such as replication and compression, obviously required CLI calls and hence, in parallel, received REST API endpoints.

Hence this blog is intended more as a “beginners guide” to issuing PowerFlex Rest API calls, for those starting out. The intention is to get a beginner up & running by showing the steps needed to issue our first REST api call to a PowerFlex system and uses tooling that is simple for a novice to use. We will explore more advanced calls in a future post. We must first assume that the user understands the basics of PowerFlex, as well as knowing how to access the PowerFlex Gateway as the admin user. This is because we issue Rest API calls to each PowerFlex system via the PowerFlex Gateway for that system – so we will assume that the Gateway has been correctly installed prior to issuing our commands. However, we will also show how to check that the Gateway is working as our first step.

For ease of simplicity, this blog uses Chrome and the “RESTED” extension for the examples shown. It is simple to issue GET commands using a web browser, while an extension such as RESTED makes it simple to issue POST requests against PowerFlex objects, but obviously developers will likely use tools such as ‘curl’, or the REST extensions of their programming language of choice.

Step One: Check To See if The Gateway Is Configured Correctly

Before issuing any REST API calls directly, we need to check if the REST API interface has been configured properly during the installation of PowerFlex. This can be done by checking directly with the PowerFlex Gateway.

Open up and login to the PowerFlex Gateway with the admin user credentials, click on the “Maintain” Tab, then click on the “Test REST API” link from the list of “Other Operations” (shown below with a red underline):

You should then be presented with a screen showing the command string that will be issued to check the Gateway:

You need to move the mouse over that “Connect to MDM on…” message string, then click on that string in order to run the test. It should come back and ask for your username credentials:

Login using the ‘admin’ user credentials, then press the “Sign In” button. The /api/login command will now execute via the REST api call from the Gateway to the MDM and should succeed if the Gateway has been installed correctly. If not… you might need to consult the second chapter of the PowerFlex REST API Guide to try and get things working correctly.

On the assumption that all went well with the /api/login command to the Gateway, you will now see the following result:

The above screen confirms that we connected to the MDM via a Rest API call, as shown by the “Obtained login token for the MDM” message in Green shown above. Now we know that the Gateway has been configured correctly, we can now move onto performing calls that actually produce something useful!

Step Two: Using a Web Browser & Authenticating Our First Session

Whenever we want to issue Restful API calls, we must first authenticate with the Gateway before we can do anything. This is done by issuing the ‘/api/login’ command, which will return an authentication token that is valid for the next 8 hours. However, the token will expire if another API call is not issued within the following 10 minutes – so beware popping out and making a cup of tea between issuing calls! You will need to make a note of the token.

Now we need to open our web browser and type in the following URL: https://<gateway-ip-address>:443/api/login . For example:

https://192.168.110.252:443/api/login

The browser should open up a box for you to enter in the admin user credentials. Once you have entered these in and clicked on “OK”, you should, by way of response, get issued with your authentication token:

This token must be entered as the “Basic Auth” text when issuing any future commands. Calls using the GET method can be issued easily via a Web browser, which will ask for the userid and authentication key upon each call made. Many commands will give verbose output, while all commands will provide output in .JSON format to allow the responses to be easily queried/manipulated afterwards.

Step Three: Issuing Our First Command Via REST – ‘queryMmdCluster’

While using any Web Browser such as Chrome or FireFox to issue ‘GET’ commands is easy to do, they do not make it easy if one wants to issue PUT or POST commands. Hence for a beginner it makes sense to install a Browser extension to make life easier when issuing REST calls. As previously mentioned, we installed the “RESTED” extension for Chrome as it is super simple to use. Other REST extensions are available but have not been tested by the author. So let us now finally issue our first REST call to the PowerFlex Gateway by querying the MDM Cluster, using the following POST call:

/api/instances/System/queryMdmCluster

Using the RESTED extension, you must still issue the ‘/api/login’ command at the start of a session, passing the admin user/password credentials as before in order to obtain the authentication key. Once armed with the key, we can now issue REST calls to the PowerFlex system. Hence a great command to start off with is the ‘queryMdmCluster’ command, which is equivalent to the native PowerFlex SCLI command “scli –query_cluster”.

When using RESTED, it is simple to construct a REST call to the PowerFlex Gateway. As this is a POST command, you must select POST as the request type, list the API command, plug in the admin user key into the “Basic Auth” section in order to use your authentication key, then set the Request Body to be type JSON and finally set the body to be an empty pair of parentheses. Then you press the “Send Request” button to issue the command:

The screen capture above shows that we got a successful API call response. Meanwhile, under the “Headers >” section of the RESTED Client, there should be a response detailing the output from the ‘mdmQueryCluster’ call:

{
  "tieBreakers": [
    {
      "opensslVersion": "N/A",
      "managementIPs": [
        "192.168.100.108"
      ],
      "ips": [
        "192.168.101.108",
        "192.168.102.108"
      ],
      "versionInfo": "R3_5.1000.0",
      "role": "TieBreaker",
      "status": "Normal",
      "name": "MDM108",
      "id": "2890e0ca07197504",
      "port": 9011
    },
    {
      "opensslVersion": "N/A",
      "managementIPs": [
        "192.168.100.106"
      ],
      "ips": [
        "192.168.101.106",
        "192.168.102.106"
      ],
      "versionInfo": "R3_5.1000.0",
      "role": "TieBreaker",
      "status": "Normal",
      "name": "MDM106",
      "id": "6a74cba971b99503",
      "port": 9011
    }
  ],
  "goodNodesNum": 5,
  "goodReplicasNum": 3,
  "clusterState": "ClusteredNormal",
  "virtualIps": [
    "192.168.101.100",
    "192.168.102.100"
  ],
  "clusterMode": "FiveNodes",
  "slaves": [
    {
      "opensslVersion": "OpenSSL 1.0.2k-fips  26 Jan 2017",
      "managementIPs": [
        "192.168.100.105"
      ],
      "ips": [
        "192.168.101.105",
        "192.168.102.105"
      ],
      "versionInfo": "R3_5.1000.0",
      "virtualInterfaces": [
        "bond1.101",
        "bond0.102"
      ],
      "role": "Manager",
      "status": "Normal",
      "name": "MDM105",
      "id": "5023c08c60958c00",
      "port": 9011
    },
    {
      "opensslVersion": "OpenSSL 1.0.2k-fips  26 Jan 2017",
      "managementIPs": [
        "192.168.100.107"
      ],
      "ips": [
        "192.168.101.107",
        "192.168.102.107"
      ],
      "versionInfo": "R3_5.1000.0",
      "virtualInterfaces": [
        "bond1.101",
        "bond0.102"
      ],
      "role": "Manager",
      "status": "Normal",
      "name": "MDM107",
      "id": "12e555a04dc42901",
      "port": 9011
    }
  ],
  "master": {
    "opensslVersion": "OpenSSL 1.0.2k-fips  26 Jan 2017",
    "managementIPs": [
      "192.168.100.109"
    ],
    "ips": [
      "192.168.101.109",
      "192.168.102.109"
    ],
    "versionInfo": "R3_5.1000.0",
    "virtualInterfaces": [
      "bond1.101",
      "bond0.102"
    ],
    "role": "Manager",
    "status": "Normal",
    "name": "MDM109",
    "id": "703114462e25c102",
    "port": 9011
  },
  "id": "4054029227369599759"
}

For comparison, see the output from the ‘scli -–query_cluster’ SCLI command, issued against the same PowerFlex system that was deployed with a 5-Node MDM Cluster:

 [root@lnx109 ~]# scli --query_cluster
Cluster:
    Mode: 5_node, State: Normal, Active: 5/5, Replicas: 3/3
    Virtual IP Addresses: 192.168.101.100, 192.168.102.100
Master MDM:
    Name: MDM109, ID: 0x703114462e25c102
        IP Addresses: 192.168.101.109, 192.168.102.109, Management IP Addresses: 192.168.100.109, Port: 9011, Virtual IP interfaces: bond1.101, bond0.102
        Status: Normal, Version: 3.5.1000
Slave MDMs:
    Name: MDM105, ID: 0x5023c08c60958c00
        IP Addresses: 192.168.101.105, 192.168.102.105, Management IP Addresses: 192.168.100.105, Port: 9011, Virtual IP interfaces: bond1.101, bond0.102
        Status: Normal, Version: 3.5.1000
    Name: MDM107, ID: 0x12e555a04dc42901
        IP Addresses: 192.168.101.107, 192.168.102.107, Management IP Addresses: 192.168.100.107, Port: 9011, Virtual IP interfaces: bond1.101, bond0.102
        Status: Normal, Version: 3.5.1000
Tie-Breakers:
    Name: MDM108, ID: 0x2890e0ca07197504
        IP Addresses: 192.168.101.108, 192.168.102.108, Port: 9011
        Status: Normal, Version: 3.5.1000
    Name: MDM106, ID: 0x6a74cba971b99503
        IP Addresses: 192.168.101.106, 192.168.102.106, Port: 9011
        Status: Normal, Version: 3.5.1000
[root@lnx109 ~]#

It can be seen from the successful example above that it is easy to issue REST API calls against PowerFlex systems. Using REST calls will give as much detail as the CLI calls that they are replicating. That brings this “Beginners Guide” to an end, but we will revisit issuing more useful PowerFlex REST API calls in a future post.

Tags: PowerFlex REST-APIREST