This article is part of a series that discusses the REST API’s of various DellEMC storage platforms. In a previous article we introduced the PowerStore REST API and showed a few tricks and best practices. In this article we will show a step-by-step example of using the DellEMC PowerStore REST API to do something useful. In this case we will go through the process of designing a REST API based workflow to perform block storage provisioning. The goal is to show the reader how to fish, so rather than sharing the code to accomplish this task we will detail the thought process so that you can build any workflow you need

If you can’t resist the urge to watch the video you will find the link at the bottom of this page 🙂

Ultimately this kind of automation will have to be built in whatever development language is required, and the choice here is really up to user. In this article we will use Postman as a way of better explaining the thought process with a graphical interface. You can follow the process along in your own laptop by installing Postman and importing the Postman collection from Project Vision. If you are new to Postman you could visit this older article where we showed how to use it, including the definition of the environment variables. Another advantage of Postman is that it provides sample code in all mainstream languages to perform any REST API call in the collection

At a glance, the process of provisioning storage consists of the following steps:

• creating a host
• creating a volume
• mapping the volume to the host

PowerStore provides two more constructs that allow for a more flexible and efficient mapping: host group and volume group. Since the concepts are identical we will focus on a single host and a single volume

A REST API is essentially a web server that provides access to certain resources (volumes and hosts in this case). Information passed back and forth between the client (Postman) and the server (the REST API server in the PowerStore array) is formatted as JSON.

When working with a REST API we will use the reference guide extensively. You will find the PowerStore REST API guide here. We will use it to:

• identify the REST API call and HTTP method that performs the task we need. Ex: “GET /volume” will allow us to get volume information
• understand what parameters we need/can pass with the request. Parameters are used to qualify a question, ex: show information about volumes larger than 10GB
• find out what headers, if any, we need to provide
• learn what status codes the REST API returns for a given call. This is important to determine what to do next in our workflow. Ex: if we get a “success” status code after creating a volume we will extract the id of the new volume from the response. On the other hand if we get an error status code we will need to extract the error message
• understand what information is going to be returned by the server and more importantly how it is formatted because we will need to extract it programmatically using our language of choice

As we mentioned when we introduced the REST API, PowerStore also provides a Swagger style documentation which can be accessed directly from the array. This provides a friendlier way of understanding a REST API than the typical PDF documentation

Now let’s move on to the actual workflow:

Step 1 – Confirm that the host we want to create doesn’t exist already … and create a token

The API calls offered for the “host” resource are shown in page 109. The first one is “GET /host” which is the one we need to “list host information”. No parameter section is displayed but we can still modify the results by following the tricks we explained in the best practices article, including what details we want to retrieve

It shows the a successful retrieval of host information will come with a status code of “200”. Therefore before attempting to read information about current hosts we will need to check that the status code matches 200

The response will show JSON something like this. The actual details will depend on what fields you requested. Then programmatically we will need to extract the names of the hosts and then if the host doesn’t exist already continue to “step 2”. If it does exist already then skip to “step 3”

Step 2 – Create the host

If we scroll down a little in the reference guide we quickly find what we need in page 110, “POST /host” to add a host:

• The parameters section tells us that we need a special parameter called a “Body” and that it is required.
• A successful host creation will produce a “201” status code
• If we click on the “create_response” we will see that the response for a successful host creation will contain the id of the host-
• If we click on the “host_create” we can see the schema, in other words the information we need to pass to build the Body. This consists of four parameters and the table tells us that 3 of them are required. The “schema” column for 2 of the fields “initiators” and “os_type” are links that show more information about what information to include. This often results in nested information which is easier to visualize in Swagger UI

Overall you will end up with a Body that looks like this

The response will return the “host id” of the host we just created. We will store it into a variable as we will need it in Step 5. Also at this point your workflow could also repeat step 1 to confirm that the host was indeed created before proceeding to the next step.

Step 3 – Confirm that the volume we want to create doesn’t exist already

Now we want to create a volume. This is very similar to step 1. The REST API resources in the PDF reference guide are sorted alphabetically. So the “volume” resource section starts in page 257. “GET /volume” allows us to query volumes that are currently provisioned. A successful response will carry the “200” status code and the response will provide the details we requested from every current volume. We can programmatically extract the names of the volumes from the JSON response to make sure the volume name we intend to create doesn’t exist already. If it does our workflow can skip to Step 5

Step 4 – Create the volume

When we scroll a bit further down in page 257 we see the “POST /volume” that allows us to create volumes. POST calls typically require Body. If we click in the “volume_create” link we can see a large number of parameters that we can include. The reference guide tells us that the only “required” ones are “name” and “size”. It is important to note that all these parameters are either strings or numbers, ie none of them have nested structures.

The status code for success is “201” and if we click in “create_response” we see that the only piece of information that will be returned is the “volume id” of the volume that was created. We will keep the “volume id” in a variable as we will need it in next step

Step 5 – Perform the mapping of the volume to the host
This API call is different from previous calls. You can find it still in the “volume” section but down in page 263. It is also a POST request because we are “creating” a mapping. As such, a Body will be required, however as we can see we need an additional parameter which is the “id” of the volume. However in this occasion we need to include it in the URL itself in between the words “volume” and “attach”. That’s what the “curly bracket” notation means. It is important to note that when we insert the “id” into the URL we do need to remove the curly brackets.

If we click in “volume_attach” we have to provide the id of either the host or the hostgroup to map the volume to. Optionally we can specify a logical unit number for host access

In the response section we see that a successful mapping operation will return a “204” status code and no content at all

At this point we have covered all the skills required to build any REST API workflow.

The Postman collection includes other block and file provisioning sample calls such as expanding an existing workflow as well as performing a deprovisioning (unmap volume, delete volume and delete host)